1 /*
2 * Copyright 2010-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License").
5 * You may not use this file except in compliance with the License.
6 * A copy of the License is located at
7 *
8 * http://aws.amazon.com/apache2.0
9 *
10 * or in the "license" file accompanying this file. This file is distributed
11 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12 * express or implied. See the License for the specific language governing
13 * permissions and limitations under the License.
14 */
15 package com.amazonaws.services.s3;
16
17 import com.amazonaws.SdkClientException;
18
19 /**
20 * S3 client configuration options such as the request access style.
21 */
22 public class S3ClientOptions {
23
24 /** The default setting for use of path-style access */
25 public static final boolean DEFAULT_PATH_STYLE_ACCESS = false;
26 /** The default setting for use of chunked encoding */
27 public static final boolean DEFAULT_CHUNKED_ENCODING_DISABLED = false;
28 /** The default setting for use of payload signing */
29 public static final boolean DEFAULT_PAYLOAD_SIGNING_ENABLED = false;
30 /** S3 accelerate is by default not enabled */
31 public static final boolean DEFAULT_ACCELERATE_MODE_ENABLED = false;
32 /** S3 dualstack endpoint is by default not enabled */
33 public static final boolean DEFAULT_DUALSTACK_ENABLED = false;
34 /** By default, clients should be created with a region. */
35 public static final boolean DEFAULT_FORCE_GLOBAL_BUCKET_ACCESS_ENABLED = false;
36 /** By default, clients will not allow a call to a different region that has been specified in an ARN */
37 public static final boolean DEFAULT_USE_ARN_REGION = false;
38 /** By default, region us-east-1 translates to the global endpoint */
39 public static final boolean DEFAULT_US_EAST_1_REGION_ENDPOINT_ENABLED = false;
40
41 /*
42 * TODO: make it final after we remove the deprecated setters.
43 */
44 private boolean pathStyleAccess;
45 private boolean chunkedEncodingDisabled;
46 private final boolean accelerateModeEnabled;
47 private final boolean payloadSigningEnabled;
48 private final boolean dualstackEnabled;
49 private final boolean forceGlobalBucketAccessEnabled;
50 private final boolean useArnRegion;
51 private final boolean regionalUsEast1EndpointEnabled;
52
53 /**
54 * @return a new S3ClientOptions builder.
55 */
56 public static Builder builder() {
57 return new Builder();
58 }
59
60 public static class Builder {
61
62 private boolean pathStyleAccess = DEFAULT_PATH_STYLE_ACCESS;
63 /** Flag for user of chunked encoding */
64 private boolean chunkedEncodingDisabled = DEFAULT_CHUNKED_ENCODING_DISABLED;
65 private boolean accelerateModeEnabled = DEFAULT_ACCELERATE_MODE_ENABLED;
66 private boolean payloadSigningEnabled = DEFAULT_PAYLOAD_SIGNING_ENABLED;
67 private boolean dualstackEnabled = DEFAULT_DUALSTACK_ENABLED;
68 private boolean forceGlobalBucketAccessEnabled = DEFAULT_FORCE_GLOBAL_BUCKET_ACCESS_ENABLED;
69 private Boolean useArnRegion = null;
70 private boolean regionalUsEast1EndpointEnabled = DEFAULT_US_EAST_1_REGION_ENDPOINT_ENABLED;
71
72 private Builder() {}
73
74 public S3ClientOptions build() {
75 if (pathStyleAccess && accelerateModeEnabled) {
76 throw new SdkClientException("Both accelerate mode and path style access are being enabled either through "
77 + "S3ClientOptions or AmazonS3ClientBuilder. These options are mutually exclusive "
78 + "and cannot be enabled together. Please disable one of them");
79 }
80
81 return new S3ClientOptions(this);
82 }
83 /**
84 * <p>
85 * Configures the client to use path-style access for all requests.
86 * </p>
87 * <p>
88 * Amazon S3 supports virtual-hosted-style and path-style access in all
89 * Regions. The path-style syntax, however, requires that you use the
90 * region-specific endpoint when attempting to access a bucket.
91 * </p>
92 * <p>
93 * The default behaviour is to detect which access style to use based on
94 * the configured endpoint (an IP will result in path-style access) and
95 * the bucket being accessed (some buckets are not valid DNS names).
96 * Setting this flag will result in path-style access being used for all
97 * requests.
98 * </p>
99 *
100 * @param pathStyleAccess
101 * True to always use path-style access.
102 * @return this Builder instance that can be used for method chaining
103 */
104 public Builder setPathStyleAccess(boolean pathStyleAccess) {
105 this.pathStyleAccess = pathStyleAccess;
106 return this;
107 }
108
109 /**
110 * <p>
111 * Configures the client to use S3 accelerate endpoint for all requests.
112 * </p>
113 * <p>
114 * A bucket by default cannot be accessed in accelerate mode. If you
115 * wish to do so, you need to enable the accelerate configuration for
116 * the bucket in advance.
117 * </p>
118 *
119 * @see AmazonS3#setBucketAccelerateConfiguration(com.amazonaws.services.s3.model.SetBucketAccelerateConfigurationRequest)
120 */
121 public Builder setAccelerateModeEnabled(boolean accelerateModeEnabled) {
122 this.accelerateModeEnabled = accelerateModeEnabled;
123 return this;
124 }
125
126 /**
127 * <p>
128 * Configures the client to sign payloads in all situations.
129 * </p>
130 * <p>
131 * Payload signing is optional when chunked encoding is not used and requests are made
132 * against an HTTPS endpoint. Under these conditions the client will by default
133 * opt to not sign payloads to optimize performance. If this flag is set to true the
134 * client will instead always sign payloads.
135 * </p>
136 * <p>
137 * <b>Note:</b> Payload signing can be expensive, particularly if transferring
138 * large payloads in a single chunk. Enabling this option will result in a performance
139 * penalty.
140 * </p>
141 *
142 * @param payloadSigningEnabled
143 * True to explicitly enable payload signing in all situations
144 */
145 public Builder setPayloadSigningEnabled(boolean payloadSigningEnabled) {
146 this.payloadSigningEnabled = payloadSigningEnabled;
147 return this;
148 }
149
150 /**
151 * <p>
152 * Configures the client to disable chunked encoding for all requests.
153 * </p>
154 * <p>
155 * The default behavior is to enable chunked encoding automatically for PutObjectRequest and
156 * UploadPartRequest. Setting this flag will result in disabling chunked encoding for all
157 * requests.
158 * </p>
159 * <p>
160 * <b>Note:</b> Enabling this option has performance implications since the checksum for the
161 * payload will have to be pre-calculated before sending the data. If your payload is large this
162 * will affect the overall time required to upload an object. Using this option is recommended
163 * only if your endpoint does not implement chunked uploading.
164 * </p>
165 *
166 * @return this Builder instance that can be used for method chaining
167 */
168 public Builder disableChunkedEncoding() {
169 this.chunkedEncodingDisabled = true;
170 return this;
171 }
172
173 /**
174 * <p>
175 * Configures the client to use the dualstack endpoint for a region
176 * <p>
177 * S3 supports dualstack endpoints which return both IPv6 and IPv4 values.
178 * Use of these endpoints is optional.
179 * </p>
180 *
181 * @return this Builder instance that can be used for method chaining
182 */
183 public Builder enableDualstack() {
184 this.dualstackEnabled = true;
185 return this;
186 }
187
188 /**
189 * <p>
190 * Force-enable global bucket access on the S3 client. Any bucket-related operations invoked against a client
191 * with this option enabled will potentially be executed against other regions than the one configured in the
192 * client in order to succeed.
193 * </p>
194 *
195 * @see AmazonS3ClientBuilder#setForceGlobalBucketAccessEnabled(Boolean)
196 * @return this Builder instance that can be used for method chaining
197 */
198 public Builder enableForceGlobalBucketAccess()
199 {
200 this.forceGlobalBucketAccessEnabled = true;
201 return this;
202 }
203
204 /**
205 * <p>
206 * If global bucket access is not enabled, this setting will enable the client to make calls to a region
207 * specified in an ARN that represents an S3 resource even if that region is different to the region the client
208 * was initialized with. This setting is disabled by default.
209 * </p>
210 *
211 * @return this Builder instance that can be used for method chaining
212 */
213 public Builder enableUseArnRegion() {
214 this.useArnRegion = true;
215 return this;
216 }
217
218 /**
219 * <p>
220 * Enable resolving region us-east-1 as a regional endpoint instead of defaulting to the global endpoint.
221 * </p>
222 *
223 * @see AmazonS3ClientBuilder#setRegionalUsEast1EndpointEnabled(Boolean)
224 * @return this Builder instance that can be used for method chaining
225 */
226 public Builder enableRegionalUsEast1Endpoint()
227 {
228 this.regionalUsEast1EndpointEnabled = true;
229 return this;
230 }
231
232 }
233
234 /**
235 * @deprecated Use {@link S3ClientOptions#builder()} to build new
236 * S3ClientOptions instead.
237 */
238 @Deprecated
239 public S3ClientOptions() {
240 this.pathStyleAccess = DEFAULT_PATH_STYLE_ACCESS;
241 this.chunkedEncodingDisabled = DEFAULT_CHUNKED_ENCODING_DISABLED;
242 this.accelerateModeEnabled = DEFAULT_ACCELERATE_MODE_ENABLED;
243 this.payloadSigningEnabled = DEFAULT_PAYLOAD_SIGNING_ENABLED;
244 this.dualstackEnabled = DEFAULT_DUALSTACK_ENABLED;
245 this.forceGlobalBucketAccessEnabled = DEFAULT_FORCE_GLOBAL_BUCKET_ACCESS_ENABLED;
246 this.useArnRegion = DEFAULT_USE_ARN_REGION;
247 this.regionalUsEast1EndpointEnabled = DEFAULT_US_EAST_1_REGION_ENDPOINT_ENABLED;
248 }
249
250 /**
251 * @deprecated Will be removed once S3ClientOptions is made an immutable
252 * class.
253 */
254 @Deprecated
255 public S3ClientOptions( S3ClientOptions other ) {
256 this.pathStyleAccess = other.pathStyleAccess;
257 this.chunkedEncodingDisabled = other.chunkedEncodingDisabled;
258 this.accelerateModeEnabled = other.accelerateModeEnabled;
259 this.payloadSigningEnabled = other.payloadSigningEnabled;
260 this.dualstackEnabled = other.dualstackEnabled;
261 this.forceGlobalBucketAccessEnabled = other.forceGlobalBucketAccessEnabled;
262 this.useArnRegion = other.useArnRegion;
263 this.regionalUsEast1EndpointEnabled = other.regionalUsEast1EndpointEnabled;
264 }
265
266 private S3ClientOptions(Builder b) {
267 this.pathStyleAccess = b.pathStyleAccess;
268 this.chunkedEncodingDisabled = b.chunkedEncodingDisabled;
269 this.accelerateModeEnabled = b.accelerateModeEnabled;
270 this.payloadSigningEnabled = b.payloadSigningEnabled;
271 this.dualstackEnabled = b.dualstackEnabled;
272 this.forceGlobalBucketAccessEnabled = b.forceGlobalBucketAccessEnabled;
273 this.useArnRegion = Boolean.TRUE.equals(b.useArnRegion);
274 this.regionalUsEast1EndpointEnabled = b.regionalUsEast1EndpointEnabled;
275 }
276
277 /**
278 * <p>
279 * Returns whether the client uses path-style access for all requests.
280 * </p>
281 * <p>
282 * Amazon S3 supports virtual-hosted-style and path-style access in all
283 * Regions. The path-style syntax, however, requires that you use the
284 * region-specific endpoint when attempting to access a bucket.
285 * </p>
286 * <p>
287 * The default behaviour is to detect which access style to use based on
288 * the configured endpoint (an IP will result in path-style access) and
289 * the bucket being accessed (some buckets are not valid DNS names).
290 * Setting this flag will result in path-style access being used for all
291 * requests.
292 * </p>
293 * @return True is the client should always use path-style access
294 */
295 public boolean isPathStyleAccess() {
296 return pathStyleAccess;
297 }
298
299 /**
300 * <p>
301 * Returns whether the client has chunked encoding disabled for all requests.
302 * </p>
303 * <p>
304 * The default behavior is to enable chunked encoding automatically for PutObjectRequest and
305 * UploadPartRequest. Setting this flag will result in disabling chunked encoding for all
306 * requests.
307 * </p>
308 * <p>
309 * <b>Note:</b> Enabling this option has performance implications since the checksum for the
310 * payload will have to be pre-calculated before sending the data. If your payload is large this
311 * will affect the overall time required to upload an object. Using this option is recommended
312 * only if your endpoint does not implement chunked uploading.
313 * </p>
314 *
315 * @return True if chunked encoding is explicitly disabled for all requests
316 */
317 public boolean isChunkedEncodingDisabled() {
318 return chunkedEncodingDisabled;
319 }
320
321 /**
322 * <p>
323 * Returns whether the client has enabled accelerate mode for getting and putting objects.
324 * </p>
325 * <p>
326 * The default behavior is to disable accelerate mode for any operations (GET, PUT, DELETE). You need to call
327 * {@link com.amazonaws.services.s3.AmazonS3Client#setBucketAccelerateConfiguration(com.amazonaws.services.s3.model.SetBucketAccelerateConfigurationRequest)}
328 * first to use this feature.
329 * </p>
330 *
331 * @return True if accelerate mode is enabled.
332 */
333 public boolean isAccelerateModeEnabled() {
334 return accelerateModeEnabled;
335 }
336
337 /**
338 * <p>
339 * Returns whether the client is configured to sign payloads in all situations.
340 * </p>
341 * <p>
342 * Payload signing is optional when chunked encoding is not used and requests are made
343 * against an HTTPS endpoint. Under these conditions the client will by default
344 * opt to not sign payloads to optimize performance. If this flag is set to true the
345 * client will instead always sign payloads.
346 * </p>
347 * <p>
348 * <b>Note:</b> Payload signing can be expensive, particularly if transferring
349 * large payloads in a single chunk. Enabling this option will result in a performance
350 * penalty.
351 * </p>
352 *
353 * @return True if body signing is explicitly enabled for all requests
354 */
355 public boolean isPayloadSigningEnabled() {
356 return payloadSigningEnabled;
357 }
358
359 /**
360 * <p>
361 * Returns whether the client is configured to use dualstack mode for
362 * accessing S3.
363 * </p>
364 *
365 * @return True if the client will use the dualstack mode
366 */
367 public boolean isDualstackEnabled() {
368 return dualstackEnabled;
369 }
370
371 /**
372 * <p>
373 * Returns whether the client should be configured with global bucket access enabled.
374 * </p>
375 * @see Builder#enableForceGlobalBucketAccess()
376 */
377 public boolean isForceGlobalBucketAccessEnabled() {
378 return this.forceGlobalBucketAccessEnabled;
379 }
380
381 /**
382 * <p>
383 * Returns whether the client should be configured to allow calls to different regions specified in an ARN.
384 * </p>
385 * @see Builder#enableUseArnRegion()
386 */
387 public boolean isUseArnRegion() {
388 return this.useArnRegion;
389 }
390
391 /**
392 * <p>
393 * Returns whether the client has enabled resolving us-east-1 to a regional endpoint.
394 * </p>
395 *
396 * @return True if regional endpoint translation is enabled
397 */
398 public boolean isRegionalUsEast1EndpointEnabled() {
399 return this.regionalUsEast1EndpointEnabled;
400 }
401
402 /**
403 * @deprecated Use {@link S3ClientOptions#builder()} to build new
404 * S3ClientOptions instead.
405 */
406 @Deprecated
407 public void setPathStyleAccess(boolean pathStyleAccess) {
408 this.pathStyleAccess = pathStyleAccess;
409 }
410
411 /**
412 * @deprecated Use {@link S3ClientOptions#builder()} to build new
413 * S3ClientOptions instead.
414 */
415 @Deprecated
416 public S3ClientOptions withPathStyleAccess(boolean pathStyleAccess) {
417 setPathStyleAccess(pathStyleAccess);
418 return this;
419 }
420
421 /**
422 * @deprecated Use {@link S3ClientOptions#builder()} to build new
423 * S3ClientOptions instead.
424 */
425 @Deprecated
426 public void setChunkedEncodingDisabled(boolean chunkedEncodingDisabled) {
427 this.chunkedEncodingDisabled = chunkedEncodingDisabled;
428 }
429
430 /**
431 * @deprecated Use {@link S3ClientOptions#builder()} to build new
432 * S3ClientOptions instead.
433 */
434 @Deprecated
435 public S3ClientOptions withChunkedEncodingDisabled(boolean chunkedEncodingDisabled) {
436 setChunkedEncodingDisabled(chunkedEncodingDisabled);
437 return this;
438 }
439
440 /**
441 * @deprecated Use {@link S3ClientOptions#builder()} to build new
442 * S3ClientOptions instead.
443 */
444 @Deprecated
445 public S3ClientOptions disableChunkedEncoding() {
446 return withChunkedEncodingDisabled(true);
447 }
448 }
449