or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

content-streaming.mdhttp-clients.mdhttp-messages.mdindex.mdmetrics.mdservice-discovery.mdtls-configuration.md
tile.json

tessl/maven-software-amazon-awssdk--http-client-spi

Service Provider Interface (SPI) for HTTP client implementations in the AWS SDK for Java v2

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

To install, run

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

index.mddocs/

AWS HTTP Client SPI

The AWS HTTP Client SPI (Service Provider Interface) provides a comprehensive set of interfaces and abstractions for implementing HTTP clients that integrate with the AWS SDK for Java v2. This SPI enables pluggable HTTP implementations while maintaining thread safety, immutability, and comprehensive configuration capabilities.

Package Information

  • Package Name: software.amazon.awssdk:http-client-spi
  • Package Type: Maven
  • Language: Java
  • Installation: Add dependency to your Maven project
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>http-client-spi</artifactId>
    <version>2.32.31</version>
</dependency>

Core Imports

import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.SdkHttpService;
import software.amazon.awssdk.http.HttpExecuteRequest;
import software.amazon.awssdk.http.SdkHttpFullRequest;
import software.amazon.awssdk.http.ContentStreamProvider;

Basic Usage

// Implementing a synchronous HTTP client
public class MyHttpClient implements SdkHttpClient {
    @Override
    public ExecutableHttpRequest prepareRequest(HttpExecuteRequest request) {
        return new MyExecutableHttpRequest(request);
    }
    
    @Override
    public String clientName() {
        return "MyHttpClientSync";
    }
    
    @Override
    public void close() {
        // Cleanup resources
    }
}

// Creating HTTP requests  
SdkHttpFullRequest request = SdkHttpFullRequest.builder()
    .protocol("https")
    .host("api.example.com")
    .port(443)
    .encodedPath("/v1/data")
    .putHeader("Content-Type", "application/json")
    .contentStreamProvider(ContentStreamProvider.fromUtf8String("{\"key\":\"value\"}"))
    .build();

// Service discovery registration
public class MyHttpService implements SdkHttpService {
    @Override
    public SdkHttpClient.Builder createHttpClientBuilder() {
        return new MyHttpClientBuilder();
    }
}

Architecture

The AWS HTTP Client SPI is built around several key architectural components:

  • HTTP Client Interfaces: Primary abstractions (SdkHttpClient, SdkAsyncHttpClient) for synchronous and asynchronous HTTP operations
  • Service Discovery: ServiceLoader-based SPI pattern (SdkHttpService, SdkAsyncHttpService) for automatic HTTP client discovery
  • Request/Response Model: Immutable HTTP message representations with builder patterns for construction
  • Content Management: Flexible content stream providers supporting various input sources and reactive streams
  • Configuration System: Type-safe execution attributes and comprehensive TLS/SSL configuration
  • Metrics Integration: Built-in metrics collection for HTTP/1.1 and HTTP/2 operations

Capabilities

HTTP Client Interfaces

Core synchronous and asynchronous HTTP client abstractions that all implementations must provide. These interfaces define the contract for making HTTP requests and handling responses.

public interface SdkHttpClient extends SdkAutoCloseable {
    ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
    default String clientName() { return "UNKNOWN"; }
}

public interface SdkAsyncHttpClient extends SdkAutoCloseable {
    CompletableFuture<Void> execute(AsyncExecuteRequest request);
    default String clientName() { return "UNKNOWN"; }
}

HTTP Client Interfaces

Request and Response Model

Immutable HTTP message representations including requests, responses, headers, and execution models. Provides builder patterns for constructing HTTP messages with comprehensive configuration options.

public interface SdkHttpFullRequest extends SdkHttpHeaders {
    Optional<ContentStreamProvider> contentStreamProvider();
    SdkHttpFullRequest.Builder toBuilder();
    static Builder builder();
}

public interface SdkHttpResponse extends SdkHttpHeaders {
    int statusCode();
    Optional<String> statusText();
    boolean isSuccessful();
}

Request and Response Model

Service Discovery

ServiceLoader-based SPI interfaces that enable automatic discovery and instantiation of HTTP client implementations on the classpath. Follows standard Java service provider patterns.

@SdkPublicApi
public interface SdkHttpService {
    SdkHttpClient.Builder createHttpClientBuilder();
}

@SdkPublicApi  
public interface SdkAsyncHttpService {
    SdkAsyncHttpClient.Builder createAsyncHttpClientFactory();
}

Service Discovery

Content Streaming

Flexible content stream providers and reactive streams publishers for handling HTTP request and response bodies. Supports various input sources and asynchronous streaming patterns.

@FunctionalInterface
public interface ContentStreamProvider {
    InputStream newStream();
    default String name() { return "Unknown"; }
    
    static ContentStreamProvider fromByteArray(byte[] bytes);
    static ContentStreamProvider fromByteArrayUnsafe(byte[] bytes);
    static ContentStreamProvider fromString(String string, Charset charset);
    static ContentStreamProvider fromUtf8String(String string);
    static ContentStreamProvider fromInputStream(InputStream inputStream);
    static ContentStreamProvider fromInputStreamSupplier(Supplier<InputStream> inputStreamSupplier);
}

public interface SdkHttpContentPublisher extends Publisher<ByteBuffer> {
    Optional<Long> contentLength();
}

Content Streaming

TLS and SSL Configuration

Comprehensive TLS/SSL configuration providers for client authentication and server certificate validation. Includes file-based and system property-based key manager providers.

@FunctionalInterface
public interface TlsKeyManagersProvider {
    KeyManager[] keyManagers();
    static TlsKeyManagersProvider noneProvider();
}

@FunctionalInterface
public interface TlsTrustManagersProvider {
    TrustManager[] trustManagers();
}

TLS and SSL Configuration

Metrics and Monitoring

Built-in metrics collection capabilities for HTTP client implementations. Provides standardized metrics for HTTP/1.1 and HTTP/2 operations including connection pooling and performance monitoring.

public final class HttpMetric {
    public static final SdkMetric<String> HTTP_CLIENT_NAME;
    public static final SdkMetric<Integer> MAX_CONCURRENCY;
    public static final SdkMetric<Integer> AVAILABLE_CONCURRENCY;
    public static final SdkMetric<Duration> CONCURRENCY_ACQUIRE_DURATION;
}

public final class Http2Metric {
    public static final SdkMetric<Integer> LOCAL_STREAM_WINDOW_SIZE_IN_BYTES;
    public static final SdkMetric<Integer> REMOTE_STREAM_WINDOW_SIZE_IN_BYTES;
}

Metrics and Monitoring

Execution Attributes

Type-safe configuration attributes for HTTP request execution. Provides a mechanism to attach metadata and configuration to HTTP requests in a type-safe manner.

@SdkPublicApi
public abstract class SdkHttpExecutionAttribute<T> extends AttributeMap.Key<T> {
    protected SdkHttpExecutionAttribute(Class<T> valueType);
    protected SdkHttpExecutionAttribute(UnsafeValueType unsafeValueType);
}

@SdkPublicApi
public final class SdkHttpExecutionAttributes 
    implements ToCopyableBuilder<SdkHttpExecutionAttributes.Builder, SdkHttpExecutionAttributes> {
    
    public <T> T getAttribute(SdkHttpExecutionAttribute<T> attribute);
    public static Builder builder();
    public Builder toBuilder();
    
    public static final class Builder {
        public <T> Builder put(SdkHttpExecutionAttribute<T> key, T value);
        public Builder putAll(Map<? extends SdkHttpExecutionAttribute<?>, ?> attributes);
        public SdkHttpExecutionAttributes build();
    }
}

Core Types

@SdkPublicApi
public enum ProtocolNegotiation {
    /** Uses prior knowledge */
    ASSUME_PROTOCOL,
    
    /** Uses Application Level Protocol Negotiation */
    ALPN
}

@SdkPublicApi  
public final class SdkCancellationException extends RuntimeException {
    public SdkCancellationException(String message);
}