com.ibm.cloud.objectstorage.services.s3

Class AmazonS3Builder<Subclass extends AmazonS3Builder,TypeToBuild extends AmazonS3>

java.lang.Object

com.ibm.cloud.objectstorage.client.builder.AwsClientBuilder<Subclass,TypeToBuild>

com.ibm.cloud.objectstorage.client.builder.AwsSyncClientBuilder<Subclass,TypeToBuild>

com.ibm.cloud.objectstorage.services.s3.AmazonS3Builder<Subclass,TypeToBuild>

Direct Known Subclasses:

AmazonS3ClientBuilder

@NotThreadSafe
public abstract class AmazonS3Builder<Subclass extends AmazonS3Builder,TypeToBuild extends AmazonS3>
extends AwsSyncClientBuilder<Subclass,TypeToBuild>

Nested Class Summary

Nested classes/interfaces inherited from class com.ibm.cloud.objectstorage.client.builder.AwsClientBuilder

AwsClientBuilder.EndpointConfiguration, AwsClientBuilder.SyncBuilderParams

Field Summary

Fields

Modifier and Type	Field and Description
protected SdkFunction<com.ibm.cloud.objectstorage.services.s3.AmazonS3ClientParamsWrapper,AmazonS3>	clientFactory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AmazonS3Builder()

Method Summary

Modifier and Type	Method and Description
Subclass	disableChunkedEncoding() Disables chunked encoding on clients built via the builder.
Subclass	enableAccelerateMode() Enables accelerate mode on clients built with the builder.
Subclass	enableDualstack() Enables dualstack mode on clients built with the builder.
Subclass	enableForceGlobalBucketAccess() Enable global bucket access for clients generated by this builder.
Subclass	enablePathStyleAccess() Enables path style access for clients built via this builder.
Subclass	enablePayloadSigning() Enables payload signing for all situations on clients built via this builder.
Boolean	isAccelerateModeEnabled()
Boolean	isChunkedEncodingDisabled()
Boolean	isDualstackEnabled()
Boolean	isForceGlobalBucketAccessEnabled()
Boolean	isPathStyleAccessEnabled()
Boolean	isPayloadSigningEnabled()
protected S3ClientOptions	resolveS3ClientOptions() Enables us-east-1 regional mode on clients built with the builder.
void	setAccelerateModeEnabled(Boolean accelerateModeEnabled) Configures the client to use S3 accelerate endpoint for all requests.
void	setChunkedEncodingDisabled(Boolean chunkedEncodingDisabled) Configures the client to disable chunked encoding for all requests.
void	setDualstackEnabled(Boolean dualstackEnabled) Configures the client to use Amazon S3 dualstack mode for all requests.
void	setForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled) Configure whether global bucket access is enabled for clients generated by this builder.
void	setPathStyleAccessEnabled(Boolean pathStyleAccessEnabled) Configures the client to use path-style access for all requests.
void	setPayloadSigningEnabled(Boolean payloadSigningEnabled) Configures the client to sign payloads in all situations.
Subclass	withAccelerateModeEnabled(Boolean accelerateModeEnabled) Configures the client to use S3 accelerate endpoint for all requests.
Subclass	withChunkedEncodingDisabled(Boolean chunkedEncodingDisabled) Configures the client to disable chunked encoding for all requests.
Subclass	withDualstackEnabled(Boolean dualstackEnabled) Configures the client to use Amazon S3 dualstack mode for all requests.
Subclass	withForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled) Configure whether global bucket access is enabled for clients generated by this builder.
Subclass	withPathStyleAccessEnabled(Boolean pathStyleAccessEnabled) Configures the client to use path-style access for all requests.
Subclass	withPayloadSigningEnabled(Boolean payloadSigningEnabled) Configures the client to sign payloads in all situations.

Methods inherited from class com.ibm.cloud.objectstorage.client.builder.AwsSyncClientBuilder

build, build

Methods inherited from class com.ibm.cloud.objectstorage.client.builder.AwsClientBuilder

getClientConfiguration, getCredentials, getEndpoint, getMetricsCollector, getRegion, getRequestHandlers, getSubclass, getSyncClientParams, setClientConfiguration, setCredentials, setEndpointConfiguration, setMetricsCollector, setRegion, setRequestHandlers, withClientConfiguration, withCredentials, withEndpointConfiguration, withIAMEndpoint, withIAMMaxRetry, withIAMTokenRefresh, withMetricsCollector, withRegion, withRegion, withRequestHandlers

Methods inherited from class java.lang.Object

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

Field Detail

clientFactory

protected final SdkFunction<com.ibm.cloud.objectstorage.services.s3.AmazonS3ClientParamsWrapper,AmazonS3> clientFactory

Constructor Detail

AmazonS3Builder

protected AmazonS3Builder()

Method Detail

isPathStyleAccessEnabled

public Boolean isPathStyleAccessEnabled()

Returns:

The current setting for path style access configured in the builder.

setPathStyleAccessEnabled

public void setPathStyleAccessEnabled(Boolean pathStyleAccessEnabled)

Configures the client to use path-style access for all requests.

Amazon S3 supports virtual-hosted-style and path-style access in all Regions. The path-style syntax, however, requires that you use the region-specific endpoint when attempting to access a bucket.

The default behaviour is to detect which access style to use based on the configured endpoint (an IP will result in path-style access) and the bucket being accessed (some buckets are not valid DNS names). Setting this flag will result in path-style access being used for all requests.

Parameters:

pathStyleAccessEnabled - True to always use path-style access.

withPathStyleAccessEnabled

public Subclass withPathStyleAccessEnabled(Boolean pathStyleAccessEnabled)

Configures the client to use path-style access for all requests.

Amazon S3 supports virtual-hosted-style and path-style access in all Regions. The path-style syntax, however, requires that you use the region-specific endpoint when attempting to access a bucket.

The default behaviour is to detect which access style to use based on the configured endpoint (an IP will result in path-style access) and the bucket being accessed (some buckets are not valid DNS names). Setting this flag will result in path-style access being used for all requests.

Parameters:

pathStyleAccessEnabled - True to always use path-style access.

Returns:

This object for method chaining.

enablePathStyleAccess

public Subclass enablePathStyleAccess()

Enables path style access for clients built via this builder.

Amazon S3 supports virtual-hosted-style and path-style access in all Regions. The path-style syntax, however, requires that you use the region-specific endpoint when attempting to access a bucket.

The default behaviour is to detect which access style to use based on the configured endpoint (an IP will result in path-style access) and the bucket being accessed (some buckets are not valid DNS names). Setting this flag will result in path-style access being used for all requests.

Returns:

This object for method chaining.

isChunkedEncodingDisabled

public Boolean isChunkedEncodingDisabled()

Returns:

The current setting for chunked encoding configured in the builder.

setChunkedEncodingDisabled

public void setChunkedEncodingDisabled(Boolean chunkedEncodingDisabled)

Configures the client to disable chunked encoding for all requests.

The default behavior is to enable chunked encoding automatically for PutObjectRequest and UploadPartRequest. Setting this flag will result in disabling chunked encoding for all requests.

Note: Enabling this option has performance implications since the checksum for the payload will have to be pre-calculated before sending the data. If your payload is large this will affect the overall time required to upload an object. Using this option is recommended only if your endpoint does not implement chunked uploading.

Parameters:

chunkedEncodingDisabled - True to disable chunked encoding.

withChunkedEncodingDisabled

public Subclass withChunkedEncodingDisabled(Boolean chunkedEncodingDisabled)

Configures the client to disable chunked encoding for all requests.

The default behavior is to enable chunked encoding automatically for PutObjectRequest and UploadPartRequest. Setting this flag will result in disabling chunked encoding for all requests.

Note: Enabling this option has performance implications since the checksum for the payload will have to be pre-calculated before sending the data. If your payload is large this will affect the overall time required to upload an object. Using this option is recommended only if your endpoint does not implement chunked uploading.

Parameters:

chunkedEncodingDisabled - True to disable chunked encoding.

Returns:

this Builder instance that can be used for method chaining

disableChunkedEncoding

public Subclass disableChunkedEncoding()

Disables chunked encoding on clients built via the builder.

The default behavior is to enable chunked encoding automatically for PutObjectRequest and UploadPartRequest. Setting this flag will result in disabling chunked encoding for all requests.

Note: Enabling this option has performance implications since the checksum for the payload will have to be pre-calculated before sending the data. If your payload is large this will affect the overall time required to upload an object. Using this option is recommended only if your endpoint does not implement chunked uploading.

Returns:

this Builder instance that can be used for method chaining

isAccelerateModeEnabled

public Boolean isAccelerateModeEnabled()

Returns:

The current setting for accelerate mode configured in the builder.

setAccelerateModeEnabled

public void setAccelerateModeEnabled(Boolean accelerateModeEnabled)

Configures the client to use S3 accelerate endpoint for all requests.

A bucket by default cannot be accessed in accelerate mode. If you wish to do so, you need to enable the accelerate configuration for the bucket in advance. To enable accelerate mode see com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest).

Parameters:

accelerateModeEnabled - True to enable accelerate mode.

withAccelerateModeEnabled

public Subclass withAccelerateModeEnabled(Boolean accelerateModeEnabled)

Configures the client to use S3 accelerate endpoint for all requests.

A bucket by default cannot be accessed in accelerate mode. If you wish to do so, you need to enable the accelerate configuration for the bucket in advance. To enable accelerate mode see com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest).

Parameters:

accelerateModeEnabled - True to enable accelerate mode.

Returns:

This object for method chaining.

enableAccelerateMode

public Subclass enableAccelerateMode()

Enables accelerate mode on clients built with the builder.

A bucket by default cannot be accessed in accelerate mode. If you wish to do so, you need to enable the accelerate configuration for the bucket in advance. To enable accelerate mode see com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest).

Returns:

This object for method chaining.

isPayloadSigningEnabled

public Boolean isPayloadSigningEnabled()

Returns:

The current setting for payload signing configured in the builder.

setPayloadSigningEnabled

public void setPayloadSigningEnabled(Boolean payloadSigningEnabled)

Configures the client to sign payloads in all situations.

Payload signing is optional when chunked encoding is not used and requests are made against an HTTPS endpoint. Under these conditions the client will by default opt to not sign payloads to optimize performance. If this flag is set to true the client will instead always sign payloads.

Note: Payload signing can be expensive, particularly if transferring large payloads in a single chunk. Enabling this option will result in a performance penalty.

Parameters:

payloadSigningEnabled - True to explicitly enable payload signing in all situations

withPayloadSigningEnabled

public Subclass withPayloadSigningEnabled(Boolean payloadSigningEnabled)

Configures the client to sign payloads in all situations.

Payload signing is optional when chunked encoding is not used and requests are made against an HTTPS endpoint. Under these conditions the client will by default opt to not sign payloads to optimize performance. If this flag is set to true the client will instead always sign payloads.

Note: Payload signing can be expensive, particularly if transferring large payloads in a single chunk. Enabling this option will result in a performance penalty.

Parameters:

payloadSigningEnabled - True to explicitly enable payload signing in all situations

Returns:

This object for method chaining.

enablePayloadSigning

public Subclass enablePayloadSigning()

Enables payload signing for all situations on clients built via this builder.

Payload signing is optional when chunked encoding is not used and requests are made against an HTTPS endpoint. Under these conditions the client will by default opt to not sign payloads to optimize performance. If this flag is set to true the client will instead always sign payloads.

Note: Payload signing can be expensive, particularly if transferring large payloads in a single chunk. Enabling this option will result in a performance penalty.

Returns:

This object for method chaining.

isDualstackEnabled

public Boolean isDualstackEnabled()

Returns:

The current setting for dualstack mode configured in the builder.

setDualstackEnabled

public void setDualstackEnabled(Boolean dualstackEnabled)

Configures the client to use Amazon S3 dualstack mode for all requests.

Parameters:

dualstackEnabled - True to enable dualstack mode.

withDualstackEnabled

public Subclass withDualstackEnabled(Boolean dualstackEnabled)

Configures the client to use Amazon S3 dualstack mode for all requests.

Parameters:

dualstackEnabled - True to enable dualstack mode.

Returns:

This object for method chaining.

enableDualstack

public Subclass enableDualstack()

Enables dualstack mode on clients built with the builder.

Returns:

This object for method chaining.

isForceGlobalBucketAccessEnabled

public Boolean isForceGlobalBucketAccessEnabled()

Returns:

Whether global bucket access is configured for clients generated by this builder.

See Also:

AmazonS3Builder.setForceGlobalBucketAccessEnabled(Boolean)

setForceGlobalBucketAccessEnabled

public void setForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled)

Configure whether global bucket access is enabled for clients generated by this builder.

When global bucket access is enabled, the region to which a request is routed may differ from the region that is configured in AwsClientBuilder.setRegion(String) in order to make the request succeed.

The following behavior is currently used when this mode is enabled:

1. All requests that do not act on an existing bucket (for example, AmazonS3Client.createBucket(String)) will be routed to the region configured by AwsClientBuilder.setRegion(String), unless the region is manually overridden with CreateBucketRequest.setRegion(String), in which case the request will be routed to the region configured in the request.
2. The first time a request is made that references an existing bucket (for example, AmazonS3Client.putObject(PutObjectRequest)) a request will be made to the region configured by AwsClientBuilder.setRegion(String) to determine the region in which the bucket was created. This location may be cached in the client for subsequent requests acting on that same bucket.

Enabling this mode has several drawbacks, because it has the potential to increase latency in the event that the location of the bucket is physically far from the location from which the request was invoked. For this reason, it is strongly advised when possible to know the location of your buckets and create a region-specific client to access that bucket.

Parameters:

forceGlobalBucketAccessEnabled - Whether global bucket access should be enabled.

withForceGlobalBucketAccessEnabled

public Subclass withForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled)

Configure whether global bucket access is enabled for clients generated by this builder.

Parameters:

forceGlobalBucketAccessEnabled - Whether global bucket access should be enabled.

Returns:

This object for method chaining.

See Also:

AmazonS3Builder.setForceGlobalBucketAccessEnabled(Boolean)

enableForceGlobalBucketAccess

public Subclass enableForceGlobalBucketAccess()

Enable global bucket access for clients generated by this builder.

Returns:

This object for method chaining.

See Also:

AmazonS3Builder.setForceGlobalBucketAccessEnabled(Boolean)

resolveS3ClientOptions

protected S3ClientOptions resolveS3ClientOptions()

Enables us-east-1 regional mode on clients built with the builder.

Returns:

This object for method chaining.