Package software.amazon.awssdk.services.s3.internal.crt

Class DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder

java.lang.Object

software.amazon.awssdk.services.s3.internal.crt.DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder

All Implemented Interfaces:

S3CrtAsyncClientBuilder, Buildable, SdkBuilder<S3CrtAsyncClientBuilder,S3AsyncClient>

Enclosing class:

DefaultS3CrtAsyncClient

public static final class DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder
extends Object
implements S3CrtAsyncClientBuilder

Constructor Summary

Constructors

Constructor	Description
DefaultS3CrtClientBuilder()

Method Summary

Modifier and Type	Method	Description
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	accelerate(Boolean accelerate)	Enables this client to use S3 Transfer Acceleration endpoints.
S3CrtAsyncClient	build()
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	checksumValidationEnabled(Boolean checksumValidationEnabled)	Option to disable checksum validation for S3AsyncClient.getObject(GetObjectRequest, Path) and S3AsyncClient.putObject(PutObjectRequest, Path).
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	credentialsProvider(IdentityProvider<? extends AwsCredentialsIdentity> credentialsProvider)	Configure the credentials that should be used to authenticate with S3.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	crossRegionAccessEnabled(Boolean crossRegionAccessEnabled)	Configures whether cross-region bucket access is enabled for clients using the configuration.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	disableS3ExpressSessionAuth(Boolean disableS3ExpressSessionAuth)	Configure whether to disable this client's usage of Session Auth for S3Express buckets and reverts to using conventional SigV4 for those.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	endpointOverride(URI endpointOverride)	Configure the endpoint override with which the SDK should communicate.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	forcePathStyle(Boolean forcePathStyle)	Forces this client to use path-style addressing for buckets.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	futureCompletionExecutor(Executor futureCompletionExecutor)	Configure the Executor that should be used to complete the CompletableFuture that is returned by the async service client.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	httpConfiguration(S3CrtHttpConfiguration configuration)	Sets the HTTP configuration to use for this client.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	initialReadBufferSizeInBytes(Long readBufferSizeInBytes)	Configure the starting buffer size the client will use to buffer the parts downloaded from S3.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	maxConcurrency(Integer maxConcurrency)	Specifies the maximum number of S3 connections that should be established during a transfer.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	maxNativeMemoryLimitInBytes(Long maxNativeMemoryLimitInBytes)	The amount of native memory that CRT is allowed to use when making requests to S3.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	minimumPartSizeInBytes(Long partSizeBytes)	Sets the minimum part size for transfer parts.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	region(Region region)	Configure the region with which the SDK should communicate.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	requestChecksumCalculation(RequestChecksumCalculation requestChecksumCalculation)	Configures the client behavior for request checksum calculation.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	responseChecksumValidation(ResponseChecksumValidation responseChecksumValidation)	Configures the client behavior for response checksum validation.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	retryConfiguration(S3CrtRetryConfiguration retryConfiguration)	Sets the Retry configuration to use for this client.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	targetThroughputInGbps(Double targetThroughputInGbps)	The target throughput for transfer requests.
DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder	thresholdInBytes(Long thresholdInBytes)	Configure the size threshold, in bytes, for when to use multipart upload.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface software.amazon.awssdk.services.s3.S3CrtAsyncClientBuilder

credentialsProvider, httpConfiguration, retryConfiguration

Methods inherited from interface software.amazon.awssdk.utils.builder.SdkBuilder

applyMutation

Constructor Detail

DefaultS3CrtClientBuilder

public DefaultS3CrtClientBuilder()

Method Detail

credentialsProvider

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder credentialsProvider(IdentityProvider<? extends AwsCredentialsIdentity> credentialsProvider)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the credentials that should be used to authenticate with S3.

The default provider will attempt to identify the credentials automatically using the following checks:

1. Java System Properties - aws.accessKeyId and aws.secretKey
2. Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
3. Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
4. Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and security manager has permission to access the variable.
5. Instance profile credentials delivered through the Amazon EC2 metadata service

If the credentials are not found in any of the locations above, an exception will be thrown at S3CrtAsyncClientBuilder.build() time.

Specified by:

credentialsProvider in interface S3CrtAsyncClientBuilder

Parameters:

credentialsProvider - the credentials to use

Returns:

This builder for method chaining.

region

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder region(Region region)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the region with which the SDK should communicate.

If this is not specified, the SDK will attempt to identify the endpoint automatically using the following logic:

1. Check the 'aws.region' system property for the region.
2. Check the 'AWS_REGION' environment variable for the region.
3. Check the {user.home}/.aws/credentials and {user.home}/.aws/config files for the region.
4. If running in EC2, check the EC2 metadata service for the region.

Specified by:

region in interface S3CrtAsyncClientBuilder

Parameters:

region - the region to be used

Returns:

this builder for method chaining.

minimumPartSizeInBytes

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder minimumPartSizeInBytes(Long partSizeBytes)

Description copied from interface: S3CrtAsyncClientBuilder

Sets the minimum part size for transfer parts. Decreasing the minimum part size causes multipart transfer to be split into a larger number of smaller parts. Setting this value too low has a negative effect on transfer speeds, causing extra latency and network communication for each part.

By default, it is 8MB. See Amazon S3 multipart upload limits for guidance.

Specified by:

minimumPartSizeInBytes in interface S3CrtAsyncClientBuilder

Parameters:

partSizeBytes - The minimum part size for transfer parts.

Returns:

this builder for method chaining.

targetThroughputInGbps

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder targetThroughputInGbps(Double targetThroughputInGbps)

Description copied from interface: S3CrtAsyncClientBuilder

The target throughput for transfer requests. Higher value means more connections will be established with S3.

Whether the transfer manager can achieve the configured target throughput depends on various factors such as the network bandwidth of the environment, whether S3CrtAsyncClientBuilder.maxConcurrency(java.lang.Integer) is configured and amount of available memory.

By default, it is 10 gigabits per second. If users want to transfer as fast as possible, it's recommended to set it to the maximum network bandwidth on the host that the application is running on. For EC2 instances, you can find network bandwidth for a specific instance type in Amazon EC2 instance type page. If you are running into out of file descriptors error, consider using S3CrtAsyncClientBuilder.maxConcurrency(Integer) to limit the number of connections.

Note: This setting affects the native memory usage used by CRT; a higher throughput value will result in a larger memory usage. Typically, a range of throughput values maps to a discrete memory limit value in CRT, with a maximum upper limit.

Specified by:

targetThroughputInGbps in interface S3CrtAsyncClientBuilder

Parameters:

targetThroughputInGbps - the target throughput in Gbps

Returns:

this builder for method chaining.

See Also:

S3CrtAsyncClientBuilder.maxConcurrency(Integer), S3CrtAsyncClientBuilder.maxNativeMemoryLimitInBytes(Long)

maxNativeMemoryLimitInBytes

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder maxNativeMemoryLimitInBytes(Long maxNativeMemoryLimitInBytes)

Description copied from interface: S3CrtAsyncClientBuilder

The amount of native memory that CRT is allowed to use when making requests to S3.

If not provided, the CRT attempts to limit native memory usage in an optimal way, based on a number of parameters such as target throughput. Therefore, only configure the memory limit explicitly when needed.

Supported range:

• Min: 1 GB
• Max: The lowest value of the supplied value and the SIZE_MAX of the system

Specified by:

maxNativeMemoryLimitInBytes in interface S3CrtAsyncClientBuilder

Parameters:

maxNativeMemoryLimitInBytes - the native memory limit in bytes

Returns:

this builder for method chaining.

See Also:

S3CrtAsyncClientBuilder.targetThroughputInGbps(Double)

maxConcurrency

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder maxConcurrency(Integer maxConcurrency)

Description copied from interface: S3CrtAsyncClientBuilder

Specifies the maximum number of S3 connections that should be established during a transfer.

If not provided, the TransferManager will calculate the optional number of connections based on S3CrtAsyncClientBuilder.targetThroughputInGbps(java.lang.Double). If the value is too low, the S3TransferManager might not achieve the specified target throughput.

Specified by:

maxConcurrency in interface S3CrtAsyncClientBuilder

Parameters:

maxConcurrency - the max number of concurrent requests

Returns:

this builder for method chaining.

See Also:

S3CrtAsyncClientBuilder.targetThroughputInGbps(Double)

endpointOverride

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder endpointOverride(URI endpointOverride)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the endpoint override with which the SDK should communicate.

Specified by:

endpointOverride in interface S3CrtAsyncClientBuilder

Parameters:

endpointOverride - the endpoint override to be used

Returns:

this builder for method chaining.

checksumValidationEnabled

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder checksumValidationEnabled(Boolean checksumValidationEnabled)

Description copied from interface: S3CrtAsyncClientBuilder

Option to disable checksum validation for S3AsyncClient.getObject(GetObjectRequest, Path) and S3AsyncClient.putObject(PutObjectRequest, Path).

Checksum validation using CRC32 is enabled by default.

Specified by:

checksumValidationEnabled in interface S3CrtAsyncClientBuilder

requestChecksumCalculation

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder requestChecksumCalculation(RequestChecksumCalculation requestChecksumCalculation)

Description copied from interface: S3CrtAsyncClientBuilder

Configures the client behavior for request checksum calculation.

Specified by:

requestChecksumCalculation in interface S3CrtAsyncClientBuilder

responseChecksumValidation

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder responseChecksumValidation(ResponseChecksumValidation responseChecksumValidation)

Description copied from interface: S3CrtAsyncClientBuilder

Configures the client behavior for response checksum validation.

Specified by:

responseChecksumValidation in interface S3CrtAsyncClientBuilder

initialReadBufferSizeInBytes

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder initialReadBufferSizeInBytes(Long readBufferSizeInBytes)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the starting buffer size the client will use to buffer the parts downloaded from S3. Maintain a larger window to keep up a high download throughput; parts cannot download in parallel unless the window is large enough to hold multiple parts. Maintain a smaller window to limit the amount of data buffered in memory.

By default, it is equal to the resolved part size * 10

Specified by:

initialReadBufferSizeInBytes in interface S3CrtAsyncClientBuilder

Parameters:

readBufferSizeInBytes - the initial read buffer size

Returns:

this builder for method chaining.

httpConfiguration

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder httpConfiguration(S3CrtHttpConfiguration configuration)

Description copied from interface: S3CrtAsyncClientBuilder

Sets the HTTP configuration to use for this client.

Specified by:

httpConfiguration in interface S3CrtAsyncClientBuilder

Parameters:

configuration - The http proxy configuration to use

Returns:

The builder of the method chaining.

accelerate

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder accelerate(Boolean accelerate)

Description copied from interface: S3CrtAsyncClientBuilder

Enables this client to use S3 Transfer Acceleration endpoints.

Specified by:

accelerate in interface S3CrtAsyncClientBuilder

forcePathStyle

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder forcePathStyle(Boolean forcePathStyle)

Description copied from interface: S3CrtAsyncClientBuilder

Forces this client to use path-style addressing for buckets.

Specified by:

forcePathStyle in interface S3CrtAsyncClientBuilder

retryConfiguration

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder retryConfiguration(S3CrtRetryConfiguration retryConfiguration)

Description copied from interface: S3CrtAsyncClientBuilder

Sets the Retry configuration to use for this client.

Specified by:

retryConfiguration in interface S3CrtAsyncClientBuilder

Parameters:

retryConfiguration - The retry configurations to be used.

Returns:

The builder of the method chaining.

crossRegionAccessEnabled

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder crossRegionAccessEnabled(Boolean crossRegionAccessEnabled)

Description copied from interface: S3CrtAsyncClientBuilder

Configures whether cross-region bucket access is enabled for clients using the configuration.

The following behavior is used when this mode is enabled:

1. This method allows enabling or disabling cross-region bucket access for clients. When cross-region bucket access is enabled, requests that do not act on an existing bucket (e.g., createBucket API) will be routed to the region configured on the client
2. The first time a request is made that references an existing bucket (e.g., putObject API), a request will be made to the client-configured region. If the bucket does not exist in this region, the service will include the actual region in the error responses. Subsequently, the API will be called using the correct region obtained from the error response.
3. This location may be cached in the client for subsequent requests to the same bucket.

Enabling this mode has several drawbacks, as it can increase latency if the bucket's location is physically far from the location of the request.Therefore, it is strongly advised, whenever possible, to know the location of your buckets and create a region-specific client to access them

Specified by:

crossRegionAccessEnabled in interface S3CrtAsyncClientBuilder

Parameters:

crossRegionAccessEnabled - Whether cross region bucket access should be enabled.

Returns:

The builder object for method chaining.

thresholdInBytes

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder thresholdInBytes(Long thresholdInBytes)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the size threshold, in bytes, for when to use multipart upload. Uploads/copies over this size will automatically use a multipart upload strategy, while uploads/copies smaller than this threshold will use a single connection to upload/copy the whole object.

Multipart uploads are easier to recover from and also potentially faster than single part uploads, especially when the upload parts can be uploaded in parallel. Because there are additional network API calls, small objects are still recommended to use a single connection for the upload. See Uploading and copying objects using multipart upload.

By default, it is the same as S3CrtAsyncClientBuilder.minimumPartSizeInBytes(Long).

Specified by:

thresholdInBytes in interface S3CrtAsyncClientBuilder

Parameters:

thresholdInBytes - the value of the threshold to set.

Returns:

an instance of this builder.

futureCompletionExecutor

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder futureCompletionExecutor(Executor futureCompletionExecutor)

Description copied from interface: S3CrtAsyncClientBuilder

Configure the Executor that should be used to complete the CompletableFuture that is returned by the async service client. By default, this is a dedicated, per-client ThreadPoolExecutor that is managed by the SDK.

The configured Executor will be invoked by the async HTTP client's I/O threads (e.g., EventLoops), which must be reserved for non-blocking behavior. Blocking an I/O thread can cause severe performance degradation, including across multiple clients, as clients are configured, by default, to share a single I/O thread pool (e.g., EventLoopGroup).

You should typically only want to customize the future-completion Executor for a few possible reasons:

1. You want more fine-grained control over the ThreadPoolExecutor used, such as configuring the pool size or sharing a single pool between multiple clients.
2. You want to add instrumentation (i.e., metrics) around how the Executor is used.

WARNING We strongly discourage using Runnable::run, which executes the future-completion directly from within the I/O thread because it may block the I/O thread and cause deadlock, especially if you are sending another SDK request in the CompletableFuture chain since the SDK may perform blocking calls in some cases.

Specified by:

futureCompletionExecutor in interface S3CrtAsyncClientBuilder

Parameters:

futureCompletionExecutor - the executor

Returns:

an instance of this builder.

disableS3ExpressSessionAuth

public DefaultS3CrtAsyncClient.DefaultS3CrtClientBuilder disableS3ExpressSessionAuth(Boolean disableS3ExpressSessionAuth)

Description copied from interface: S3CrtAsyncClientBuilder

Configure whether to disable this client's usage of Session Auth for S3Express buckets and reverts to using conventional SigV4 for those.

Specified by:

disableS3ExpressSessionAuth in interface S3CrtAsyncClientBuilder

Parameters:

disableS3ExpressSessionAuth - whether Session Auth for S3Express should be disabled

Returns:

an instance of this builder

build

public S3CrtAsyncClient build()

Specified by:

build in interface Buildable

Specified by:

build in interface S3CrtAsyncClientBuilder

Specified by:

build in interface SdkBuilder<S3CrtAsyncClientBuilder,S3AsyncClient>