com.ibm.cloud.objectstorage.services.s3.AmazonS3Builder Maven / Gradle / Ivy
Show all versions of ibm-cos-java-sdk-s3 Show documentation
/*
* Copyright 2011-2023 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.ibm.cloud.objectstorage.services.s3;
import com.ibm.cloud.objectstorage.ClientConfigurationFactory;
import com.ibm.cloud.objectstorage.annotation.NotThreadSafe;
import com.ibm.cloud.objectstorage.annotation.SdkTestInternalApi;
import com.ibm.cloud.objectstorage.client.builder.AwsSyncClientBuilder;
import com.ibm.cloud.objectstorage.internal.SdkFunction;
import com.ibm.cloud.objectstorage.regions.AwsRegionProvider;
import com.ibm.cloud.objectstorage.services.s3.model.CreateBucketRequest;
import com.ibm.cloud.objectstorage.services.s3.model.PutObjectRequest;
@NotThreadSafe
public abstract class AmazonS3Builder extends AwsSyncClientBuilder {
private static final AmazonS3ClientConfigurationFactory CLIENT_CONFIG_FACTORY = new AmazonS3ClientConfigurationFactory();
private static final SdkFunction DEFAULT_CLIENT_FACTORY = new SdkFunction() {
@Override
public AmazonS3 apply(AmazonS3ClientParamsWrapper params) {
return new AmazonS3Client(params);
}
};
protected final SdkFunction clientFactory;
private Boolean pathStyleAccessEnabled;
private Boolean chunkedEncodingDisabled;
private Boolean accelerateModeEnabled;
private Boolean payloadSigningEnabled;
private Boolean dualstackEnabled;
private Boolean forceGlobalBucketAccessEnabled;
//IBM unsupported
// private Boolean useArnRegionEnabled;
// private Boolean regionalUsEast1EndpointEnabled;
protected AmazonS3Builder() {
super(CLIENT_CONFIG_FACTORY);
this.clientFactory = DEFAULT_CLIENT_FACTORY;
}
@SdkTestInternalApi
AmazonS3Builder(SdkFunction clientFactory,
ClientConfigurationFactory clientConfigFactory,
AwsRegionProvider regionProvider) {
super(clientConfigFactory, regionProvider);
this.clientFactory = clientFactory;
}
/**
* @return The current setting for path style access configured in the builder.
*/
public Boolean isPathStyleAccessEnabled() {
return 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.
*
* @param pathStyleAccessEnabled True to always use path-style access.
*/
public void setPathStyleAccessEnabled(Boolean pathStyleAccessEnabled) {
this.pathStyleAccessEnabled = 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.
*
* @param pathStyleAccessEnabled True to always use path-style access.
* @return This object for method chaining.
*/
public Subclass withPathStyleAccessEnabled(Boolean pathStyleAccessEnabled) {
setPathStyleAccessEnabled(pathStyleAccessEnabled);
return getSubclass();
}
/**
* 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.
*
* @return This object for method chaining.
*/
public Subclass enablePathStyleAccess() {
setPathStyleAccessEnabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return The current setting for chunked encoding configured in the builder.
*/
public Boolean isChunkedEncodingDisabled() {
return 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.
*
* @param chunkedEncodingDisabled True to disable chunked encoding.
*/
public void setChunkedEncodingDisabled(Boolean chunkedEncodingDisabled) {
this.chunkedEncodingDisabled = 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.
*
* @param chunkedEncodingDisabled True to disable chunked encoding.
* @return this Builder instance that can be used for method chaining
*/
public Subclass withChunkedEncodingDisabled(Boolean chunkedEncodingDisabled) {
setChunkedEncodingDisabled(chunkedEncodingDisabled);
return getSubclass();
}
/**
* 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.
*
* @return this Builder instance that can be used for method chaining
*/
public Subclass disableChunkedEncoding() {
setChunkedEncodingDisabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return The current setting for accelerate mode configured in the builder.
*/
public Boolean isAccelerateModeEnabled() {
return 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 {@link com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest)}.
*
*
* @param accelerateModeEnabled True to enable accelerate mode.
* @return This object for method chaining.
*/
public void setAccelerateModeEnabled(Boolean accelerateModeEnabled) {
this.accelerateModeEnabled = 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 {@link com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest)}.
*
*
* @param accelerateModeEnabled True to enable accelerate mode.
* @return This object for method chaining.
*/
public Subclass withAccelerateModeEnabled(Boolean accelerateModeEnabled) {
setAccelerateModeEnabled(accelerateModeEnabled);
return getSubclass();
}
/**
* 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 {@link com.ibm.cloud.objectstorage.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.ibm.cloud.objectstorage.services.s3.model.SetBucketAccelerateConfigurationRequest)}.
*
*
* @return This object for method chaining.
*/
public Subclass enableAccelerateMode() {
setAccelerateModeEnabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return The current setting for payload signing configured in the builder.
*/
public Boolean isPayloadSigningEnabled() {
return 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.
*
* @param payloadSigningEnabled True to explicitly enable payload signing in all situations
*/
public void setPayloadSigningEnabled(Boolean payloadSigningEnabled) {
this.payloadSigningEnabled = 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.
*
* @param payloadSigningEnabled True to explicitly enable payload signing in all situations
* @return This object for method chaining.
*/
public Subclass withPayloadSigningEnabled(Boolean payloadSigningEnabled) {
setPayloadSigningEnabled(payloadSigningEnabled);
return getSubclass();
}
/**
* 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.
*
* @return This object for method chaining.
*/
public Subclass enablePayloadSigning() {
setPayloadSigningEnabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return The current setting for dualstack mode configured in the builder.
*/
public Boolean isDualstackEnabled() {
return dualstackEnabled;
}
/**
* Configures the client to use Amazon S3 dualstack mode for all requests.
*
* @param dualstackEnabled True to enable dualstack mode.
* @return This object for method chaining.
*/
public void setDualstackEnabled(Boolean dualstackEnabled) {
this.dualstackEnabled = dualstackEnabled;
}
/**
* Configures the client to use Amazon S3 dualstack mode for all requests.
*
* @param dualstackEnabled True to enable dualstack mode.
* @return This object for method chaining.
*/
public Subclass withDualstackEnabled(Boolean dualstackEnabled) {
setDualstackEnabled(dualstackEnabled);
return getSubclass();
}
/**
* Enables dualstack mode on clients built with the builder.
* @return This object for method chaining.
*/
public Subclass enableDualstack() {
setDualstackEnabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return Whether global bucket access is configured for clients generated by this builder.
* @see #setForceGlobalBucketAccessEnabled(Boolean)
*/
public Boolean isForceGlobalBucketAccessEnabled() {
return 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 {@link #setRegion(String)} in order to make the request succeed.
*
*
* The following behavior is currently used when this mode is enabled:
*
* - All requests that do not act on an existing bucket (for example, {@link AmazonS3Client#createBucket(String)})
* will be routed to the region configured by {@link #setRegion(String)}, unless the region is manually overridden
* with {@link CreateBucketRequest#setRegion(String)}, in which case the request will be routed to the region
* configured in the request.
* - The first time a request is made that references an existing bucket (for example,
* {@link AmazonS3Client#putObject(PutObjectRequest)}) a request will be made to the region configured by
* {@link #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.
*
* @param forceGlobalBucketAccessEnabled Whether global bucket access should be enabled.
*/
public void setForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled) {
this.forceGlobalBucketAccessEnabled = forceGlobalBucketAccessEnabled;
}
/**
* Configure whether global bucket access is enabled for clients generated by this builder.
*
* @see #setForceGlobalBucketAccessEnabled(Boolean)
* @param forceGlobalBucketAccessEnabled Whether global bucket access should be enabled.
* @return This object for method chaining.
*/
public Subclass withForceGlobalBucketAccessEnabled(Boolean forceGlobalBucketAccessEnabled) {
setForceGlobalBucketAccessEnabled(forceGlobalBucketAccessEnabled);
return getSubclass();
}
/**
* Enable global bucket access for clients generated by this builder.
*
* @see #setForceGlobalBucketAccessEnabled(Boolean)
* @return This object for method chaining.
*/
public Subclass enableForceGlobalBucketAccess() {
setForceGlobalBucketAccessEnabled(Boolean.TRUE);
return getSubclass();
}
/**
* @return Whether us-east-1 should resolve to its regional endpoint or the default global endpoint.
* @see #setRegionalUsEast1EndpointEnabled(Boolean)
*/
//IBM unsupported
// public Boolean isRegionalUsEast1EndpointEnabled() {
// return regionalUsEast1EndpointEnabled;
// }
/**
* Configures the client to resolve region us-east-1 region to its regional endpoint instead of the
* global endpoint for all requests.
*
* The default value for this value is false, configuring this region resolve to the global s3 endpoint.
*
*
* There are three ways to enable this option. In order of precedence:
*
* - Configuring the S3 client directly through this builder,
* using {@link #setRegionalUsEast1EndpointEnabled(Boolean)}
* - Setting the environment variable AWS_S3_US_EAST_1_REGIONAL_ENDPOINT to regional
* - Setting the shared config/profile file option s3_us_east_1_regional_endpoint regional
*
* Environment variable options override config values and direct configurations override environment variable
* settings. The accepted values for environment variable and config option are regional and legacy.
* Setting the values to legacy does not affect any change in behavior unless the intention is for the
* environment variable to override a regional setting in the config file.
*
*
* @param regionalUsEast1EndpointEnabled True to enable us-east-1 regional mode.
* @return This object for method chaining.
*/
//IBM unsupported
// public void setRegionalUsEast1EndpointEnabled(Boolean regionalUsEast1EndpointEnabled) {
// this.regionalUsEast1EndpointEnabled = regionalUsEast1EndpointEnabled;
// }
/**
* Configures the client to resolve region us-east-1 region to its regional endpoint instead of the
* global endpoint for all requests.
*
* @param regionalUsEast1EndpointEnabled True to enable us-east-1 regional mode.
* @return This object for method chaining.
* @see #setRegionalUsEast1EndpointEnabled(Boolean)
*/
//IBM unsupported
// public Subclass withRegionalUsEast1EndpointEnabled(Boolean regionalUsEast1EndpointEnabled) {
// setRegionalUsEast1EndpointEnabled(regionalUsEast1EndpointEnabled);
// return getSubclass();
// }
/**
* Enables us-east-1 regional mode on clients built with the builder.
* @return This object for method chaining.
*/
//IBM unsupported
// public Subclass enableRegionalUsEast1Endpoint() {
// setRegionalUsEast1EndpointEnabled(Boolean.TRUE);
// return getSubclass();
// }
protected S3ClientOptions resolveS3ClientOptions() {
final S3ClientOptions.Builder builder = S3ClientOptions.builder();
if (Boolean.TRUE.equals(this.chunkedEncodingDisabled)) {
builder.disableChunkedEncoding();
}
if (this.payloadSigningEnabled != null) {
builder.setPayloadSigningEnabled(this.payloadSigningEnabled);
}
if (this.accelerateModeEnabled != null) {
builder.setAccelerateModeEnabled(this.accelerateModeEnabled);
}
if (this.pathStyleAccessEnabled != null) {
builder.setPathStyleAccess(this.pathStyleAccessEnabled);
}
if(Boolean.TRUE.equals(this.dualstackEnabled)) {
builder.enableDualstack();
}
if(Boolean.TRUE.equals(this.forceGlobalBucketAccessEnabled)) {
builder.enableForceGlobalBucketAccess();
}
//IBM unsupported
// if(Boolean.TRUE.equals(this.useArnRegionEnabled)) {
// builder.enableUseArnRegion();
// }
// if(Boolean.TRUE.equals(this.regionalUsEast1EndpointEnabled)) {
// builder.enableRegionalUsEast1Endpoint();
// }
return builder.build();
}
}