Client configuration - Amazon SDK for Java 2.x
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Client configuration

In 1.x, SDK client configuration was modified by setting a ClientConfiguration instance on the client or client builder. In version 2.x, the client configuration is split into separate configuration classes. With the separate configuration classes, you can configure different HTTP clients for async versus synchronous clients but still use the same ClientOverrideConfiguration class.

Example of client configuration in version 1.x
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
Example of synchronous client configuration in version 2.x
ProxyConfiguration.Builder proxyConfig = ProxyConfiguration.builder(); ApacheHttpClient.Builder httpClientBuilder = ApacheHttpClient.builder() .proxyConfiguration(proxyConfig.build()); ClientOverrideConfiguration.Builder overrideConfig = ClientOverrideConfiguration.builder(); DynamoDbClient client = DynamoDbClient.builder() .httpClientBuilder(httpClientBuilder) .overrideConfiguration(overrideConfig.build()) .build();
Example of asynchronous client configuration in version 2.x
NettyNioAsyncHttpClient.Builder httpClientBuilder = NettyNioAsyncHttpClient.builder(); ClientOverrideConfiguration.Builder overrideConfig = ClientOverrideConfiguration.builder(); ClientAsyncConfiguration.Builder asyncConfig = ClientAsyncConfiguration.builder(); DynamoDbAsyncClient client = DynamoDbAsyncClient.builder() .httpClientBuilder(httpClientBuilder) .overrideConfiguration(overrideConfig.build()) .asyncConfiguration(asyncConfig.build()) .build();

HTTP clients

Notable changes

  • In version 2.x, you can change which HTTP client to use at runtime by specifying an implementation using clientBuilder.httpClientBuilder.

  • When you pass an HTTP client by using clientBuilder.httpClient to a service client builder, the HTTP client is not closed by default if the service client closes. This allows you to share HTTP clients between service clients.

  • Asynchronous HTTP clients now use non-blocking IO.

  • Some operations now use HTTP/2 for improved performance.

Settings changes

Setting 1.x 2.x Sync, Apache 2.x Async, Netty
ClientConfiguration clientConfig = new ClientConfiguration()
ApacheHttpClient.Builder httpClientBuilder = ApacheHttpClient.builder()
NettyNioAsyncHttpClient.Builder httpClientBuilder = NettyNioAsyncHttpClient.builder()
Max connections
clientConfig.setMaxConnections(...) clientConfig.withMaxConnections(...)
httpClientBuilder.maxConnections(...)
httpClientBuilder.maxConcurrency(...)
Connection timeout
clientConfig.setConnectionTimeout(...) clientConfig.withConnectionTimeout(...)
httpClientBuilder.connectionTimeout(...) httpClientBuilder.connectionAcquisitionTimeout(...)
httpClientBuilder.connectionTimeout(...)
Socket timeout
clientConfig.setSocketTimeout(...) clientConfig.withSocketTimeout(...)
httpClientBuilder.socketTimeout(...)
httpClientBuilder.writeTimeout(...) httpClientBuilder.readTimeout(...)
Connection TTL
clientConfig.setConnectionTTL(...) clientConfig.withConnectionTTL(...)
httpClientBuilder.connectionTimeToLive(...)
httpClientBuilder.connectionTimeToLive(...)
Connection max idle
clientConfig.setConnectionMaxIdleMillis(...) clientConfig.withConnectionMaxIdleMillis(...)
httpClientBuilder.connectionMaxIdleTime(...)
httpClientBuilder.connectionMaxIdleTime(...)
Validate after inactivity
clientConfig.setValidateAfterInactivityMillis(...) clientConfig.withValidateAfterInactivityMillis(...)
Not supported (Request Feature) Not supported (Request Feature)
Local address
clientConfig.setLocalAddress(...) clientConfig.withLocalAddress(...)
httpClientBuilder.localAddress(...)
Not supported
Expect-continue enabled
clientConfig.setUseExpectContinue(...) clientConfig.withUseExpectContinue(...)
httpClientBuilder.expectContinueEnabled(...)
Not supported (Request Feature)
Connection reaper
clientConfig.setUseReaper(...) clientConfig.withReaper(...)
httpClientBuilder.useIdleConnectionReaper(...)
httpClientBuilder.useIdleConnectionReaper(...)
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
DynamoDbClient.builder() .httpClientBuilder(httpClientBuilder) .build()
DynamoDbAsyncClient.builder() .httpClientBuilder(httpClientBuilder) .build()

HTTP client proxies

Settings 1.x 2.x Sync, Apache 2.x Async, Netty
ClientConfiguration clientConfig = new ClientConfiguration()
ProxyConfiguration.Builder proxyConfig = ProxyConfiguration.builder()
ProxyConfiguration.Builder proxyConfig = ProxyConfiguration.builder()
Proxy host
clientConfig.setProxyHost(...) clientConfig.withProxyHost(...)
proxyConfig.endpoint(...)
proxyConfig.host(...)
Proxy port
clientConfig.setProxyPort(...) clientConfig.withProxyPort(...)
proxyConfig.endpoint(...)

Proxy port is embedded in endpoint

proxyConfig.port(...)
Proxy username
clientConfig.setProxyUsername(...) clientConfig.withProxyUsername(...)
proxyConfig.username(...)
proxyConfig.username(...)
Proxy password
clientConfig.setProxyPassword(...) clientConfig.withProxyPassword(...)
proxyConfig.password(...)
proxyConfig.password(...)
Proxy domain
clientConfig.setProxyDomain(...) clientConfig.withProxyDomain(...)
proxyConfig.ntlmDomain(...)
Not Supported (Request Feature)
Proxy workstation
clientConfig.setProxyWorkspace(...) clientConfig.withProxyWorkstation(...)
proxyConfig.ntlmWorkstation(...)
Not Supported (Request Feature)
Proxy authentication methods
clientConfig.setProxyAuthenticationMethods(...) clientConfig.withProxyAuthenticationMethods(...)

Not Supported

Not Supported (Request Feature)
Preemptive basic proxy authentication
clientConfig.setPreemptiveBasicProxyAuth(...) clientConfig.withPreemptiveBasicProxyAuth(...)
proxyConfig.preemptiveBasicAuthenticationEnabled(...)
Not Supported (Request Feature)
Non-proxy hosts
clientConfig.setNonProxyHosts(...) clientConfig.withNonProxyHosts(...)
proxyConfig.nonProxyHosts(...)
proxyConfig.nonProxyHosts(...)
Disable socket proxy
clientConfig.setDisableSocketProxy(...) clientConfig.withDisableSocketProxy(...)
Not Supported (Request Feature) Not Supported (Request Feature)
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
httpClientBuilder.proxyConfiguration( proxyConfig.build())
httpClientBuilder.proxyConfiguration( proxyConfig.build())

Client overrides

Setting 1.x 2.x
ClientConfiguration clientConfig = new ClientConfiguration()
ClientOverrideConfiguration.Builder overrideConfig = ClientOverrideConfiguration.builder()
User agent prefix
clientConfig.setUserAgentPrefix(...) clientConfig.withUserAgentPrefix(...)
overrideConfig.advancedOption( SdkAdvancedClientOption.USER_AGENT_PREFIX, ...)
User agent suffix
clientConfig.setUserAgentSuffix(...) clientConfig.withUserAgentSuffix(...)
overrideConfig.advancedOption( SdkAdvancedClientOption.USER_AGENT_SUFFIX, ...)
Signer
clientConfig.setSignerOverride(...) clientConfig.withSignerOverride(...)
overrideConfig.advancedOption( SdkAdvancedClientOption.SIGNER, ...)
Additional headers
clientConfig.addHeader(...) clientConfig.withHeader(...)
overrideConfig.putHeader(...)
Request timeout
clientConfig.setRequestTimeout(...) clientConfig.withRequestTimeout(...)
overrideConfig.apiCallAttemptTimeout(...)
Client execution timeout
clientConfig.setClientExecutionTimeout(...) clientConfig.withClientExecutionTimeout(...)
overrideConfig.apiCallTimeout(...)
Use Gzip
clientConfig.setUseGzip(...) clientConfig.withGzip(...)

Not Supported (Request Feature)

Socket buffer size hint
clientConfig.setSocketBufferSizeHints(...) clientConfig.withSocketBufferSizeHints(...)
Not Supported (Request Feature)
Cache response metadata
clientConfig.setCacheResponseMetadata(...) clientConfig.withCacheResponseMetadata(...)
Not Supported (Request Feature)
Response metadata cache size
clientConfig.setResponseMetadataCacheSize(...) clientConfig.withResponseMetadataCacheSize(...)
Not Supported (Request Feature)
DNS resolver
clientConfig.setDnsResolver(...) clientConfig.withDnsResolver(...)
Not Supported (Request Feature)
TCP keepalive
clientConfig.setUseTcpKeepAlive(...) clientConfig.withTcpKeepAlive(...)

This option is now in the HTTP Client configuration

- ApacheHttpClient.builder().tcpKeepAlive(true) - NettyNioAsyncHttpClient.builder().tcpKeepAlive(true)
Secure random
clientConfig.setSecureRandom(...) clientConfig.withSecureRandom(...)
Not Supported (Request Feature)
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
DynamoDbClient.builder() .httpClientBuilder(httpClientBuilder) .build()

Client override retries

Setting 1.x 2.x
ClientConfiguration clientConfig = new ClientConfiguration()
RetryPolicy.Builder retryPolicy = RetryPolicy.builder()
Max error retry
clientConfig.setMaxErrorRetry(...) clientConfig.withMaxErrorRetry(...)
retryPolicy.numRetries(...)
Use throttled retries
clientConfig.setUseThrottleRetries(...) clientConfig.withUseThrottleRetries(...)
Not supported
Max consecutive retries before throttling
clientConfig.setMaxConsecutiveRetriesBeforeThrottling(...) clientConfig.withMaxConsecutiveRetriesBeforeThrottling(...)
Not supported
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
DynamoDbClient.builder() .httpClientBuilder(httpClientBuilder) .build()

Asynchronous clients

Setting 1.x 2.x
ClientAsyncConfiguration.Builder asyncConfig = ClientAsyncConfiguration.builder()
Executor
AmazonDynamoDBAsyncClientBuilder.standard() .withExecutorFactory(...) .build()
asyncConfig.advancedOption( SdkAdvancedAsyncClientOption.FUTURE_COMPLETION_EXECUTOR, ...)
DynamoDbAsyncClient.builder() .asyncConfiguration(asyncConfig) .build()

Other client changes

The following ClientConfiguration option from 1.x has changed in 2.x of the SDK and doesn't have a direct equivalent.

Setting 1.x 2.x equivalent
Protocol
clientConfig.setProtocol(Protocol.HTTP) clientConfig.withProtocol(Protocol.HTTP)

The protocol setting is HTTPS by default. To modify the setting, specify the protocol setting an HTTP endpoint on the client builder:

clientBuilder.endpointOverride( URI.create("http://..."))