public interface AmazonS3 extends S3DirectSpi
Provides an interface for accessing the Amazon S3 web service.
Note: Do not directly implement this interface, new methods are added to it regularly.
Extend from AbstractAmazonS3 instead.
Amazon S3 provides storage for the Internet, and is designed to make web-scale computing easier for developers.
The Amazon S3 Java SDK provides a simple interface that can be used to store and retrieve any amount of data, at any time, from anywhere on the web. It gives any developer access to the same highly scalable, reliable, secure, fast, inexpensive infrastructure that Amazon uses to run its own global network of web sites. The service aims to maximize benefits of scale and to pass those benefits on to developers.
For more information about Amazon S3, please see http://aws.amazon.com/s3
ExtendAbstractAmazonS3 if you are implementing AmazonS3 interface.
AbstractAmazonS3 provides a default implementation for all the methods in
this interface.| Modifier and Type | Field and Description |
|---|---|
static String |
ENDPOINT_PREFIX
The region metadata service name for computing region endpoints.
|
| Modifier and Type | Method and Description |
|---|---|
void |
abortMultipartUpload(AbortMultipartUploadRequest request)
Aborts a multipart upload.
|
void |
addLegalHold(AddLegalHoldRequest addLegalHoldRequest)
Adds a legal hold to the specified object in the specified bucket.
|
void |
addLegalHold(String bucketName,
String key,
String legalHoldId)
Adds a legal hold to the specified object in the specified bucket.
|
void |
changeObjectStorageClass(String bucketName,
String key,
StorageClass newStorageClass)
Deprecated.
this operation will not retain the ACL's or SSE parameters
associated with the given Amazon S3 object. Use
AmazonS3.copyObject(CopyObjectRequest)
instead. |
CompleteMultipartUploadResult |
completeMultipartUpload(CompleteMultipartUploadRequest request)
Completes a multipart upload by assembling previously uploaded parts.
|
CopyObjectResult |
copyObject(CopyObjectRequest copyObjectRequest)
Copies a source object to a new destination in Amazon S3.
|
CopyObjectResult |
copyObject(String sourceBucketName,
String sourceKey,
String destinationBucketName,
String destinationKey)
Copies a source object to a new destination in Amazon S3.
|
CopyPartResult |
copyPart(CopyPartRequest copyPartRequest)
Copies a source object to a part of a multipart upload.
|
Bucket |
createBucket(CreateBucketRequest createBucketRequest)
Creates a new Amazon S3 bucket in the region that the client was created
in.
|
Bucket |
createBucket(String bucketName)
Creates a new Amazon S3 bucket with the specified name in the region
that the client was created in.
|
Bucket |
createBucket(String bucketName,
Region region)
Deprecated.
Use regional endpoint and call
AmazonS3.createBucket(String) instead. |
Bucket |
createBucket(String bucketName,
String region)
Deprecated.
Use regional endpoint and call
AmazonS3.createBucket(String) instead. |
void |
deleteBucket(DeleteBucketRequest deleteBucketRequest)
Deletes the specified bucket.
|
void |
deleteBucket(String bucketName)
Deletes the specified bucket.
|
void |
deleteBucketCrossOriginConfiguration(DeleteBucketCrossOriginConfigurationRequest deleteBucketCrossOriginConfigurationRequest)
Delete the cross origin configuration for the specified bucket.
|
void |
deleteBucketCrossOriginConfiguration(String bucketName)
Delete the cross origin configuration for the specified bucket.
|
void |
deleteBucketLifecycleConfiguration(DeleteBucketLifecycleConfigurationRequest deleteBucketLifecycleConfigurationRequest)
Removes the lifecycle configuration for the bucket specified.
|
void |
deleteBucketLifecycleConfiguration(String bucketName)
Removes the lifecycle configuration for the bucket specified.
|
void |
deleteBucketWebsiteConfiguration(DeleteBucketWebsiteConfigurationRequest deleteBucketWebsiteConfigurationRequest)
This operation removes the website configuration for a bucket.
|
void |
deleteBucketWebsiteConfiguration(String bucketName)
This operation removes the website configuration for a bucket.
|
void |
deleteLegalHold(DeleteLegalHoldRequest deleteLegalHoldRequest)
Deletes a legal hold for the specified object in the specified bucket.
|
void |
deleteLegalHold(String bucketName,
String key,
String legalHoldId)
Deletes a legal hold for the specified object in the specified bucket.
|
void |
deleteObject(DeleteObjectRequest deleteObjectRequest)
Deletes the specified object in the specified bucket.
|
void |
deleteObject(String bucketName,
String key)
Deletes the specified object in the specified bucket.
|
DeleteObjectsResult |
deleteObjects(DeleteObjectsRequest deleteObjectsRequest)
Deletes multiple objects in a single bucket from S3.
|
void |
deleteVersion(DeleteVersionRequest deleteVersionRequest)
Deletes a specific version of an object in the specified bucket.
|
void |
deleteVersion(String bucketName,
String key,
String versionId)
Deletes a specific version of the specified object in the specified
bucket.
|
boolean |
doesBucketExist(String bucketName)
Deprecated.
By
AmazonS3.doesBucketExistV2(String) which will correctly throw an exception when
credentials are invalid instead of returning true. See
Issue #1256. |
boolean |
doesBucketExistV2(String bucketName)
Checks if the specified bucket exists.
|
boolean |
doesObjectExist(String bucketName,
String objectName) |
void |
extendObjectRetention(ExtendObjectRetentionRequest extendObjectRetentionRequest)
Extends the retention period of a protected object in a protected vault.
|
void |
extendObjectRetention(String bucketName,
String key,
Long additionalRetentionPeriod,
Long extendRetentionFromCurrentTime,
Date newRetentionExpirationDate,
Long newRetentionPeriod)
Extends the retention period of a protected object in a protected vault.
|
URL |
generatePresignedUrl(GeneratePresignedUrlRequest generatePresignedUrlRequest)
Returns a pre-signed URL for accessing an Amazon S3 resource.
|
URL |
generatePresignedUrl(String bucketName,
String key,
Date expiration)
Returns a pre-signed URL for accessing an Amazon S3 resource.
|
URL |
generatePresignedUrl(String bucketName,
String key,
Date expiration,
HttpMethod method)
Returns a pre-signed URL for accessing an Amazon S3 resource.
|
AccessControlList |
getBucketAcl(GetBucketAclRequest getBucketAclRequest)
Gets the
AccessControlList (ACL) for the specified Amazon S3
bucket. |
AccessControlList |
getBucketAcl(String bucketName)
Gets the
AccessControlList (ACL) for the specified Amazon S3 bucket. |
BucketCrossOriginConfiguration |
getBucketCrossOriginConfiguration(GetBucketCrossOriginConfigurationRequest getBucketCrossOriginConfigurationRequest)
Gets the cross origin configuration for the specified bucket, or null if
no configuration has been established.
|
BucketCrossOriginConfiguration |
getBucketCrossOriginConfiguration(String bucketName)
Gets the cross origin configuration for the specified bucket, or null if
the specified bucket does not exists, or an empty list if no
configuration has been established.
|
FASPConnectionInfo |
getBucketFaspConnectionInfo(GetBucketFaspConnectionInfoRequest getBucketFASPConnectionInfoRequest)
Gets the FASP Connection Info for a particular bucket.
|
FASPConnectionInfo |
getBucketFaspConnectionInfo(String bucketName)
Gets the FASP Connection Info for a particular bucket.
|
BucketLifecycleConfiguration |
getBucketLifecycleConfiguration(GetBucketLifecycleConfigurationRequest getBucketLifecycleConfigurationRequest)
Gets the lifecycle configuration for the specified bucket, or null if
the specified bucket does not exists, or an empty list if no
configuration has been established.
|
BucketLifecycleConfiguration |
getBucketLifecycleConfiguration(String bucketName)
Gets the lifecycle configuration for the specified bucket, or null if
the specified bucket does not exists, or an empty list if no
configuration has been established.
|
BucketProtectionConfiguration |
getBucketProtection(String bucketName)
Gets the protection configuration for the specified bucket.
|
BucketProtectionConfiguration |
getBucketProtectionConfiguration(GetBucketProtectionConfigurationRequest getBucketProtectionRequest) |
BucketVersioningConfiguration |
getBucketVersioningConfiguration(GetBucketVersioningConfigurationRequest getBucketVersioningConfigurationRequest)
Returns the versioning configuration for the specified bucket.
|
BucketVersioningConfiguration |
getBucketVersioningConfiguration(String bucketName)
Returns the versioning configuration for the specified bucket.
|
BucketWebsiteConfiguration |
getBucketWebsiteConfiguration(GetBucketWebsiteConfigurationRequest getBucketWebsiteConfigurationRequest)
Returns the website configuration for the specified bucket.
|
BucketWebsiteConfiguration |
getBucketWebsiteConfiguration(String bucketName)
Returns the website configuration for the specified bucket.
|
S3ResponseMetadata |
getCachedResponseMetadata(AmazonWebServiceRequest request)
Gets additional metadata for a previously executed successful request.
|
S3Object |
getObject(GetObjectRequest getObjectRequest)
Gets the object stored in Amazon S3 under the specified bucket and
key.
|
ObjectMetadata |
getObject(GetObjectRequest getObjectRequest,
File destinationFile)
Gets the object metadata for the object stored
in Amazon S3 under the specified bucket and key,
and saves the object contents to the
specified file.
|
S3Object |
getObject(String bucketName,
String key)
Gets the object stored in Amazon S3 under the specified bucket and key.
|
AccessControlList |
getObjectAcl(GetObjectAclRequest getObjectAclRequest)
Gets the
AccessControlList (ACL) for the specified object in Amazon S3. |
AccessControlList |
getObjectAcl(String bucketName,
String key)
Gets the
AccessControlList (ACL) for the specified object in Amazon S3. |
AccessControlList |
getObjectAcl(String bucketName,
String key,
String versionId)
Gets the
AccessControlList (ACL) for the specified object
with the specified version in Amazon S3. |
String |
getObjectAsString(String bucketName,
String key)
Retrieves and decodes the contents of an S3 object to a String.
|
ObjectMetadata |
getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)
Gets the metadata for the specified Amazon S3 object without
actually fetching the object itself.
|
ObjectMetadata |
getObjectMetadata(String bucketName,
String key)
Gets the metadata for the specified Amazon S3 object without
actually fetching the object itself.
|
Region |
getRegion()
Returns the region with which the client is configured.
|
String |
getRegionName()
Returns a string representation of the region with which this
client is configured
|
Owner |
getS3AccountOwner()
Gets the current owner of the AWS account
that the authenticated sender of the request is using.
|
Owner |
getS3AccountOwner(GetS3AccountOwnerRequest getS3AccountOwnerRequest)
Gets the current owner of the AWS account
that the authenticated sender of the request is using.
|
URL |
getUrl(String bucketName,
String key)
Returns an URL for the object stored in the specified bucket and
key.
|
HeadBucketResult |
headBucket(HeadBucketRequest headBucketRequest)
Performs a head bucket operation on the requested bucket name.
|
InitiateMultipartUploadResult |
initiateMultipartUpload(InitiateMultipartUploadRequest request)
Initiates a multipart upload and returns an InitiateMultipartUploadResult
which contains an upload ID.
|
List<Bucket> |
listBuckets()
Returns a list of all Amazon S3 buckets that the
authenticated sender of the request owns.
|
List<Bucket> |
listBuckets(ListBucketsRequest listBucketsRequest)
Returns a list of all Amazon S3 buckets that the
authenticated sender of the request owns.
|
ListBucketsExtendedResponse |
listBucketsExtended()
Returns a list of all Cloud Object Storage (COS) S3 buckets that the
authenticated sender of the request owns.
|
ListBucketsExtendedResponse |
listBucketsExtended(ListBucketsExtendedRequest listBucketsExtendedRequest)
Returns a list of all Cloud Object Storage (COS) S3 buckets that the
authenticated sender of the request owns.
|
ListLegalHoldsResult |
listLegalHolds(ListLegalHoldsRequest listLegalHoldsRequest)
Returns a list of legal holds for the specified key in the specified bucket.
|
ListLegalHoldsResult |
listLegalHolds(String bucketName,
String key)
Returns a list of legal holds for the specified key in the specified bucket.
|
MultipartUploadListing |
listMultipartUploads(ListMultipartUploadsRequest request)
Lists in-progress multipart uploads.
|
ObjectListing |
listNextBatchOfObjects(ListNextBatchOfObjectsRequest listNextBatchOfObjectsRequest)
Provides an easy way to continue a truncated object listing and retrieve
the next page of results.
|
ObjectListing |
listNextBatchOfObjects(ObjectListing previousObjectListing)
Provides an easy way to continue a truncated object listing and retrieve
the next page of results.
|
VersionListing |
listNextBatchOfVersions(com.ibm.cloud.objectstorage.services.s3.model.ListNextBatchOfVersionsRequest listNextBatchOfVersionsRequest)
Provides an easy way to continue a truncated
VersionListing and retrieve
the next page of results. |
VersionListing |
listNextBatchOfVersions(VersionListing previousVersionListing)
Provides an easy way to continue a truncated
VersionListing and retrieve
the next page of results. |
ObjectListing |
listObjects(ListObjectsRequest listObjectsRequest)
Returns a list of summary information about the objects in the specified
bucket.
|
ObjectListing |
listObjects(String bucketName)
Returns a list of summary information about the objects in the specified
buckets.
|
ObjectListing |
listObjects(String bucketName,
String prefix)
Returns a list of summary information about the objects in the specified
bucket.
|
ListObjectsV2Result |
listObjectsV2(ListObjectsV2Request listObjectsV2Request) |
ListObjectsV2Result |
listObjectsV2(String bucketName) |
ListObjectsV2Result |
listObjectsV2(String bucketName,
String prefix) |
PartListing |
listParts(ListPartsRequest request)
Lists the parts that have been uploaded for a specific multipart upload.
|
VersionListing |
listVersions(com.ibm.cloud.objectstorage.services.s3.model.ListVersionsRequest listVersionsRequest)
Returns a list of summary information about the versions in the specified
bucket.
|
VersionListing |
listVersions(String bucketName,
String prefix)
Returns a list of summary information about the versions in the specified
bucket.
|
VersionListing |
listVersions(String bucketName,
String prefix,
String keyMarker,
String versionIdMarker,
String delimiter,
Integer maxResults)
Returns a list of summary information about the versions in the specified
bucket.
|
PutObjectResult |
putObject(PutObjectRequest putObjectRequest)
Uploads a new object to the specified Amazon S3 bucket.
|
PutObjectResult |
putObject(String bucketName,
String key,
File file)
Uploads the specified file to Amazon S3 under the specified bucket and
key name.
|
PutObjectResult |
putObject(String bucketName,
String key,
InputStream input,
ObjectMetadata metadata)
Uploads the specified input stream and object metadata to Amazon S3 under
the specified bucket and key name.
|
PutObjectResult |
putObject(String bucketName,
String key,
String content)
Encodes a String into the contents of an S3 object.
|
void |
restoreObject(RestoreObjectRequest request)
Restore an object, which was transitioned to Amazon Glacier from Amazon
S3 when it was expired, into Amazon S3 again.
|
void |
restoreObject(String bucketName,
String key,
int expirationInDays)
Restore an object, which was transitioned to Amazon Glacier from Amazon
S3 when it was expired, into Amazon S3 again.
|
void |
setBucketAcl(SetBucketAclRequest setBucketAclRequest)
Sets the
AccessControlList for the specified Amazon S3 bucket. |
void |
setBucketAcl(String bucketName,
AccessControlList acl)
Sets the
AccessControlList for the specified Amazon S3 bucket. |
void |
setBucketAcl(String bucketName,
CannedAccessControlList acl)
Sets the
CannedAccessControlList for the specified Amazon S3 bucket using one of
the pre-configured CannedAccessControlLists. |
void |
setBucketCrossOriginConfiguration(SetBucketCrossOriginConfigurationRequest setBucketCrossOriginConfigurationRequest)
Sets the cross origin configuration for the specified bucket.
|
void |
setBucketCrossOriginConfiguration(String bucketName,
BucketCrossOriginConfiguration bucketCrossOriginConfiguration)
Sets the cross origin configuration for the specified bucket.
|
void |
setBucketLifecycleConfiguration(SetBucketLifecycleConfigurationRequest setBucketLifecycleConfigurationRequest)
Sets the lifecycle configuration for the specified bucket.
|
void |
setBucketLifecycleConfiguration(String bucketName,
BucketLifecycleConfiguration bucketLifecycleConfiguration)
Sets the lifecycle configuration for the specified bucket.
|
void |
setBucketProtection(String bucketName,
BucketProtectionConfiguration protectionConfiguration) |
void |
setBucketProtectionConfiguration(SetBucketProtectionConfigurationRequest setBucketProtectionRequest)
Set the protection configuration for the specified bucket.
|
void |
setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
Sets the versioning configuration for the specified bucket.
|
void |
setBucketWebsiteConfiguration(SetBucketWebsiteConfigurationRequest setBucketWebsiteConfigurationRequest)
Sets the website configuration for the specified bucket.
|
void |
setBucketWebsiteConfiguration(String bucketName,
BucketWebsiteConfiguration configuration)
Sets the website configuration for the specified bucket.
|
void |
setEndpoint(String endpoint)
Overrides the default endpoint for this client.
|
void |
setObjectAcl(SetObjectAclRequest setObjectAclRequest)
Sets the
AccessControlList for the specified Amazon S3 object
with an optional version ID. |
void |
setObjectAcl(String bucketName,
String key,
AccessControlList acl)
Sets the
AccessControlList for the specified object in Amazon S3. |
void |
setObjectAcl(String bucketName,
String key,
CannedAccessControlList acl)
Sets the
CannedAccessControlList for the specified object in
Amazon S3 using one
of the pre-configured CannedAccessControlLists. |
void |
setObjectAcl(String bucketName,
String key,
String versionId,
AccessControlList acl)
Sets the
CannedAccessControlList for the specified object
with the specified version in Amazon S3. |
void |
setObjectAcl(String bucketName,
String key,
String versionId,
CannedAccessControlList acl)
Sets the
CannedAccessControlList for the specified object with the specified
version ID in Amazon S3 using one of the pre-configured
CannedAccessControlLists. |
void |
setObjectRedirectLocation(String bucketName,
String key,
String newRedirectLocation)
Deprecated.
this operation will not retain the ACL's or SSE parameters
associated with the given Amazon S3 object. Use
AmazonS3.copyObject(CopyObjectRequest)
instead. |
void |
setRegion(Region region)
An alternative to
AmazonS3.setEndpoint(String), sets the
regional endpoint for this client's service calls. |
void |
setS3ClientOptions(S3ClientOptions clientOptions)
Override the default S3 client options for this client.
|
void |
shutdown()
Shuts down this client object, releasing any resources that might be held
open.
|
UploadPartResult |
uploadPart(UploadPartRequest request)
Uploads a part in a multipart upload.
|
AmazonS3Waiters |
waiters() |
static final String ENDPOINT_PREFIX
void setEndpoint(String endpoint)
Overrides the default endpoint for this client. Use this method to send requests to the specified AWS region.
Pass the endpoint (e.g. "s3.amazonaws.com") or a full
URL, including the protocol (e.g. "https://s3.amazonaws.com"). If the
protocol is not specified, the protocol from this client's
ClientConfiguration is used.
endpoint - The endpoint (e.g. "s3.amazonaws.com") or the full URL,
including the protocol (e.g. "https://s3.amazonaws.com"), of
the region-specific AWS endpoint this client will communicate
with.IllegalArgumentException - If the specified endpoint is not a valid URL endpoint.void setRegion(Region region) throws IllegalArgumentException
AmazonS3.setEndpoint(String), sets the
regional endpoint for this client's service calls. Callers can use this
method to control which AWS region they want to work with.
This method is not threadsafe. A region should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
By default, all service endpoints in all regions use the https protocol.
To use http instead, specify it in the ClientConfiguration
supplied at construction.
region - The region this client will communicate with. See
Region.getRegion(com.ibm.cloud.objectstorage.regions.Regions) for
accessing a given region.IllegalArgumentException - If the given region is null, or if this service isn't
available in the given region. See
Region.isServiceSupported(String)Region.getRegion(com.ibm.cloud.objectstorage.regions.Regions),
Region.createClient(Class, com.ibm.cloud.objectstorage.auth.AWSCredentialsProvider, ClientConfiguration)void setS3ClientOptions(S3ClientOptions clientOptions)
Override the default S3 client options for this client.
clientOptions - The S3 client options to use.@Deprecated void changeObjectStorageClass(String bucketName, String key, StorageClass newStorageClass) throws SdkClientException, AmazonServiceException
AmazonS3.copyObject(CopyObjectRequest)
instead.Changes the Amazon S3 storage class for a specified object. Amazon S3 offers multiple storage classes for developers' different needs.
Note that changing the storage class of an object in a bucket that has enabled versioning creates a new version of the object with the new storage class. The existing version of the object persists in the current storage class.
bucketName - The name of the bucket containing the object.key - The key of the object within the specified bucket.newStorageClass - The new storage class for the specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.@Deprecated void setObjectRedirectLocation(String bucketName, String key, String newRedirectLocation) throws SdkClientException, AmazonServiceException
AmazonS3.copyObject(CopyObjectRequest)
instead.Changes the Amazon S3 redirect location for a specific object.
bucketName - The name of the bucket containing the object.key - The key of the object within the specified bucket.newRedirectLocation - The new redirect location for the specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.ObjectListing listObjects(String bucketName) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the objects in the specified buckets. List results are always returned in lexicographic (alphabetical) order.
Because buckets can contain a virtually unlimited number of keys, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
ObjectListing.isTruncated() method to see if the returned
listing is complete or if additional calls are needed to get
more results. Alternatively, use the
AmazonS3Client.listNextBatchOfObjects(ObjectListing) method as
an easy way to get the next page of object listings.
The total number of keys in a bucket doesn't substantially affect list performance.
bucketName - The name of the Amazon S3 bucket to list.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listObjects(String, String),
AmazonS3Client.listObjects(ListObjectsRequest),
AWS API DocumentationObjectListing listObjects(String bucketName, String prefix) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the objects in the specified bucket. Depending on request parameters, additional information is returned, such as common prefixes if a delimiter was specified. List results are always returned in lexicographic (alphabetical) order.
Because buckets can contain a virtually unlimited number of keys, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
ObjectListing.isTruncated() method to see if the returned
listing is complete or if additional calls are needed to get
more results. Alternatively, use the
AmazonS3Client.listNextBatchOfObjects(ObjectListing) method as
an easy way to get the next page of object listings.
For example, consider a bucket that contains the following keys:
listObjects with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an ObjectListing is returned that contains one key
("foo/boo") and one entry in the common prefixes list ("foo/bar/").
To see deeper into the virtual hierarchy, make another
call to listObjects setting the prefix parameter to any interesting
common prefix to list the individual keys under that prefix.
The total number of keys in a bucket doesn't substantially affect list performance.
bucketName - The name of the Amazon S3 bucket to list.prefix - An optional parameter restricting the response to keys
beginning with the specified prefix. Use prefixes to
separate a bucket into different sets of keys,
similar to how a file system organizes files
into directories.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listObjects(String),
AmazonS3Client.listObjects(ListObjectsRequest),
AWS API DocumentationObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the objects in the specified bucket. Depending on the request parameters, additional information is returned, such as common prefixes if a delimiter was specified. List results are always returned in lexicographic (alphabetical) order.
Because buckets can contain a virtually unlimited number of keys, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
ObjectListing.isTruncated() method to see if the returned
listing is complete or if additional calls are needed to get
more results. Alternatively, use the
AmazonS3Client.listNextBatchOfObjects(ObjectListing) method as
an easy way to get the next page of object listings.
Calling ListObjectsRequest.setDelimiter(String)
sets the delimiter, allowing groups of keys that share the
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, similar to how a file system organizes files
into directories. These common prefixes can be retrieved
through the ObjectListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
listObjects with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an ObjectListing is returned that contains one key
("foo/boo") and one entry in the common prefixes list ("foo/bar/").
To see deeper into the virtual hierarchy, make another
call to listObjects setting the prefix parameter to any interesting
common prefix to list the individual keys under that prefix.
The total number of keys in a bucket doesn't substantially affect list performance.
listObjectsRequest - The request object containing all options for listing the
objects in a specified bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listObjects(String),
AmazonS3Client.listObjects(String, String),
AWS API DocumentationListObjectsV2Result listObjectsV2(String bucketName) throws SdkClientException, AmazonServiceException
ListObjectsV2Result listObjectsV2(String bucketName, String prefix) throws SdkClientException, AmazonServiceException
ListObjectsV2Result listObjectsV2(ListObjectsV2Request listObjectsV2Request) throws SdkClientException, AmazonServiceException
ListBucketsExtendedResponse listBucketsExtended() throws SdkClientException, AmazonServiceException
Returns a list of all Cloud Object Storage (COS) S3 buckets that the authenticated sender of the request owns.
Users must authenticate with a valid credentials that are registered with COS. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.
SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in COS S3 while processing the
request.ListBucketsExtendedResponse listBucketsExtended(ListBucketsExtendedRequest listBucketsExtendedRequest) throws SdkClientException, AmazonServiceException
Returns a list of all Cloud Object Storage (COS) S3 buckets that the authenticated sender of the request owns.
Users must authenticate with a valid credentials that are registered with COS. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.
listBucketsExtendedResponse - The request containing all of the options related to the extended listing
of buckets.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in COS S3 while processing the
request.ObjectListing listNextBatchOfObjects(ObjectListing previousObjectListing) throws SdkClientException, AmazonServiceException
Provides an easy way to continue a truncated object listing and retrieve the next page of results.
To continue the object listing and retrieve the next page of results,
call the initial ObjectListing from one of the
listObjects methods.
If truncated
(indicated when ObjectListing.isTruncated() returns true),
pass the ObjectListing back into this method
in order to retrieve the
next page of results. Continue using this method to
retrieve more results until the returned ObjectListing indicates that
it is not truncated.
previousObjectListing - The previous truncated ObjectListing.
If a
non-truncated ObjectListing is passed in, an empty
ObjectListing is returned without ever contacting
Amazon S3.ObjectListing results, beginning immediately
after the last result in the specified previous ObjectListing.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listObjects(String),
AmazonS3Client.listObjects(String, String),
AmazonS3Client.listObjects(ListObjectsRequest),
AmazonS3Client.listNextBatchOfObjects(ListNextBatchOfObjectsRequest),
AWS API DocumentationObjectListing listNextBatchOfObjects(ListNextBatchOfObjectsRequest listNextBatchOfObjectsRequest) throws SdkClientException, AmazonServiceException
Provides an easy way to continue a truncated object listing and retrieve the next page of results.
To continue the object listing and retrieve the next page of results,
call the initial ObjectListing from one of the
listObjects methods.
If truncated
(indicated when ObjectListing.isTruncated() returns true),
pass the ObjectListing back into this method
in order to retrieve the
next page of results. Continue using this method to
retrieve more results until the returned ObjectListing indicates that
it is not truncated.
listNextBatchOfObjectsRequest - The request object for listing next batch of objects using the previous
truncated ObjectListing. If a
non-truncated ObjectListing is passed in by the request object, an empty
ObjectListing is returned without ever contacting
Amazon S3.ObjectListing results, beginning immediately
after the last result in the specified previous ObjectListing.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listObjects(String),
AmazonS3Client.listObjects(String, String),
AmazonS3Client.listObjects(ListObjectsRequest),
AmazonS3Client.listNextBatchOfObjects(ObjectListing),
AWS API DocumentationVersionListing listVersions(String bucketName, String prefix) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the versions in the specified bucket.
The returned version summaries are ordered first by key and then by version. Keys are sorted lexicographically (alphabetically) while versions are sorted from most recent to least recent. Both versions with data and delete markers are included in the results.
Because buckets can contain a virtually unlimited number of versions, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
VersionListing.isTruncated() method to determine if the
returned listing is complete or if additional calls are needed to get
more results. Callers are
encouraged to use
AmazonS3.listNextBatchOfVersions(VersionListing) as an easy way
to get the next page of results.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
bucketName - The name of the Amazon S3 bucket whose versions are to be
listed.prefix - An optional parameter restricting the response to keys
beginning with the specified prefix. Use prefixes to
separate a bucket into different sets of keys,
similar to how a file system organizes files
into directories.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listVersions(ListVersionsRequest),
AmazonS3Client.listVersions(String, String, String, String, String, Integer),
AWS API DocumentationVersionListing listNextBatchOfVersions(VersionListing previousVersionListing) throws SdkClientException, AmazonServiceException
Provides an easy way to continue a truncated VersionListing and retrieve
the next page of results.
Obtain the initial
VersionListing from one of the listVersions methods. If the result
is truncated (indicated when VersionListing.isTruncated() returns true),
pass the VersionListing back into this method in order to retrieve the
next page of results. From there, continue using this method to
retrieve more results until the returned VersionListing indicates that
it is not truncated.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
previousVersionListing - The previous truncated VersionListing.
If a
non-truncated VersionListing is passed in, an empty
VersionListing is returned without ever contacting
Amazon S3.VersionListing results, beginning immediately
after the last result in the specified previous VersionListing.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listVersions(String, String),
AmazonS3Client.listVersions(ListVersionsRequest),
AmazonS3Client.listVersions(String, String, String, String, String, Integer),
AmazonS3Client.listNextBatchOfVersions(ListNextBatchOfVersionsRequest),
AWS API DocumentationVersionListing listNextBatchOfVersions(com.ibm.cloud.objectstorage.services.s3.model.ListNextBatchOfVersionsRequest listNextBatchOfVersionsRequest) throws SdkClientException, AmazonServiceException
Provides an easy way to continue a truncated VersionListing and retrieve
the next page of results.
Obtain the initial
VersionListing from one of the listVersions methods. If the result
is truncated (indicated when VersionListing.isTruncated() returns true),
pass the VersionListing back into this method in order to retrieve the
next page of results. From there, continue using this method to
retrieve more results until the returned VersionListing indicates that
it is not truncated.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
listNextBatchOfVersionsRequest - The request object for listing next batch of versions using the previous
truncated VersionListing. If a
non-truncated VersionListing is passed in by the request object, an empty
VersionListing is returned without ever contacting
Amazon S3.VersionListing results, beginning immediately
after the last result in the specified previous VersionListing.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listVersions(String, String),
AmazonS3Client.listVersions(ListVersionsRequest),
AmazonS3Client.listVersions(String, String, String, String, String, Integer),
AmazonS3Client.listNextBatchOfVersions(VersionListing),
AWS API DocumentationVersionListing listVersions(String bucketName, String prefix, String keyMarker, String versionIdMarker, String delimiter, Integer maxResults) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the versions in the specified bucket.
The returned version summaries are ordered first by key and then by version. Keys are sorted lexicographically (alphabetically) and versions are sorted from most recent to least recent. Versions with data and delete markers are included in the results.
Because buckets can contain a virtually unlimited number of versions, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
VersionListing.isTruncated() method to determine if the
returned listing is complete or if additional calls are needed
to get more results.
Callers are
encouraged to use
AmazonS3.listNextBatchOfVersions(VersionListing) as an easy way
to get the next page of results.
The keyMarker and versionIdMarker parameters allow
callers to specify where to start the version listing.
The delimiter parameter allows groups of keys that share a
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, much like how a file system organizes
files into directories. These common prefixes can be retrieved
by calling the VersionListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
listVersions with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, a VersionListing is returned that contains:
To see deeper into the virtual hierarchy, make
another call to listVersions setting the prefix parameter to any
interesting common prefix to list the individual versions under that
prefix.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
bucketName - The name of the Amazon S3 bucket whose versions are to be
listed.prefix - An optional parameter restricting the response to keys that
begin with the specified prefix. Use prefixes to
separate a bucket into different sets of keys,
similar to how a file system organizes files
into directories.keyMarker - Optional parameter indicating where in the sorted list of all
versions in the specified bucket to begin returning results.
Results are always ordered first lexicographically (i.e.
alphabetically) and then from most recent version to least
recent version. If a keyMarker is used without a
versionIdMarker, results begin immediately after that key's
last version. When a keyMarker is used with a versionIdMarker,
results begin immediately after the version with the specified
key and version ID.
This enables pagination; to get the next page of results use
the next key marker and next version ID marker (from
VersionListing.getNextKeyMarker() and
VersionListing.getNextVersionIdMarker()) as the
markers for the next request to list versions, or use the
convenience method
AmazonS3.listNextBatchOfVersions(VersionListing)
versionIdMarker - Optional parameter indicating where in the sorted list of all
versions in the specified bucket to begin returning results.
Results are always ordered first lexicographically (i.e.
alphabetically) and then from most recent version to least
recent version. A keyMarker must be specified when specifying
a versionIdMarker. Results begin immediately after the version
with the specified key and version ID.
This enables pagination; to get the next page of results use
the next key marker and next version ID marker (from
VersionListing.getNextKeyMarker() and
VersionListing.getNextVersionIdMarker()) as the
markers for the next request to list versions, or use the
convenience method
AmazonS3.listNextBatchOfVersions(VersionListing)
delimiter - Optional parameter that causes keys that contain the same
string between the prefix and the first occurrence of the
delimiter to be rolled up into a single result element in the
VersionListing.getCommonPrefixes() list. These
rolled-up keys are not returned elsewhere in the response. The
most commonly used delimiter is "/", which simulates a
hierarchical organization similar to a file system directory
structure.maxResults - Optional parameter indicating the maximum number of results to
include in the response. Amazon S3 might return fewer than
this, but will not return more. Even if maxKeys is not
specified, Amazon S3 will limit the number of results in the
response.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listVersions(String, String),
AmazonS3Client.listVersions(ListVersionsRequest),
AmazonS3Client.listNextBatchOfVersions(VersionListing),
AWS API DocumentationVersionListing listVersions(com.ibm.cloud.objectstorage.services.s3.model.ListVersionsRequest listVersionsRequest) throws SdkClientException, AmazonServiceException
Returns a list of summary information about the versions in the specified bucket.
The returned version summaries are ordered first by key and then by version. Keys are sorted lexicographically (alphabetically) and versions are sorted from most recent to least recent. Versions with data and delete markers are included in the results.
Because buckets can contain a virtually unlimited number of versions, the
complete results of a list query can be extremely large. To manage large
result sets, Amazon S3 uses pagination to split them into multiple
responses. Always check the
VersionListing.isTruncated() method to determine if the
returned listing is complete or if additional calls are needed
to get more results.
Callers are
encouraged to use
AmazonS3.listNextBatchOfVersions(VersionListing) as an easy way
to get the next page of results.
The keyMarker and versionIdMarker parameters allow
callers to specify where to start the version listing.
The delimiter parameter allows groups of keys that share a
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, much like how a file system organizes
files into directories. These common prefixes can be retrieved
by calling the VersionListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
listVersions with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, a VersionListing is returned that contains:
To see deeper into the virtual hierarchy, make
another call to listVersions setting the prefix parameter to any
interesting common prefix to list the individual versions under that
prefix.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
listVersionsRequest - The request object containing all options for listing the
versions in a specified bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.listVersions(String, String),
AmazonS3Client.listVersions(String, String, String, String, String, Integer),
AmazonS3Client.listNextBatchOfVersions(VersionListing),
AWS API DocumentationOwner getS3AccountOwner() throws SdkClientException, AmazonServiceException
Gets the current owner of the AWS account that the authenticated sender of the request is using.
The caller must authenticate with a valid AWS Access Key ID that is registered with AWS.
SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getS3AccountOwner(GetS3AccountOwnerRequest)Owner getS3AccountOwner(GetS3AccountOwnerRequest getS3AccountOwnerRequest) throws SdkClientException, AmazonServiceException
Gets the current owner of the AWS account that the authenticated sender of the request is using.
The caller must authenticate with a valid AWS Access Key ID that is registered with AWS.
getS3AccountOwnerRequest - The request object for retrieving the S3 account owner.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getS3AccountOwner()@Deprecated boolean doesBucketExist(String bucketName) throws SdkClientException, AmazonServiceException
AmazonS3.doesBucketExistV2(String) which will correctly throw an exception when
credentials are invalid instead of returning true. See
Issue #1256.bucketName - The name of the bucket to check.true if the specified bucket exists in
Amazon S3; the value false if there is no bucket in
Amazon S3 with that name.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.createBucket(CreateBucketRequest)boolean doesBucketExistV2(String bucketName) throws SdkClientException, AmazonServiceException
Internally this uses the AmazonS3.getBucketAcl(String) operation to determine
whether the bucket exists.
bucketName - The name of the bucket to check.true if the specified bucket exists in
Amazon S3; the value false if there is no bucket in
Amazon S3 with that name.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.createBucket(CreateBucketRequest)HeadBucketResult headBucket(HeadBucketRequest headBucketRequest) throws SdkClientException, AmazonServiceException
headBucketRequest - The request containing the bucket name.HeadBucketResult if the bucket exists and you have
permission to access it. Otherwise, the method will throw an
AmazonServiceException with status code '404 Not Found' if the bucket
does not exist, '403 Forbidden' if the user does not have access to the
bucket, or '301 Moved Permanently' if the bucket is in a different region
than the client is configured withSdkClientException - If any errors are encountered in the client while making the request or handling
the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the request.List<Bucket> listBuckets() throws SdkClientException, AmazonServiceException
Returns a list of all Amazon S3 buckets that the authenticated sender of the request owns.
Users must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.
SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.listBuckets(ListBucketsRequest),
AWS API DocumentationList<Bucket> listBuckets(ListBucketsRequest listBucketsRequest) throws SdkClientException, AmazonServiceException
Returns a list of all Amazon S3 buckets that the authenticated sender of the request owns.
Users must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.
listBucketsRequest - The request containing all of the options related to the listing
of buckets.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.listBuckets(),
AWS API DocumentationBucket createBucket(CreateBucketRequest createBucketRequest) throws SdkClientException, AmazonServiceException
Creates a new Amazon S3 bucket in the region that the client was created
in. If no region or AWS S3 endpoint was specified when creating the client,
the bucket will be created within the default (US) region, Region.US_Standard
or the region that was specified within the CreateBucketRequest.region field.
Requests that specify a region using the CreateBucketRequest.setRegion(String)
method or through either constructor that allows passing in the region will return an
error if the client is not configured to use the default (US) region, Region.US_Standard
or the same region that is specified in the request.
Every object stored in Amazon S3 is contained within a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, any name can be used for objects. However, bucket names must be unique across all of Amazon S3.
Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
To conform with DNS requirements, the following constraints apply:
There are no limits to the number of objects that can be stored in a bucket. Performance does not vary based on the number of buckets used. Store all objects within a single bucket or organize them across several buckets.
Buckets cannot be nested; buckets cannot be created within other buckets.
Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup routine that runs less often.
To create a bucket, authenticate with an account that has a valid AWS Access Key ID and is registered with Amazon S3. Anonymous requests are never allowed to create buckets.
createBucketRequest - The request object containing all options for creating an Amazon S3
bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.Bucket createBucket(String bucketName) throws SdkClientException, AmazonServiceException
Creates a new Amazon S3 bucket with the specified name in the region
that the client was created in. If no region or AWS S3 endpoint was specified
when creating the client, the bucket will be created within the default
(US) region, Region.US_Standard.
Every object stored in Amazon S3 is contained within a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, any name can be used for objects. However, bucket names must be unique across all of Amazon S3.
Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
To conform with DNS requirements, the following constraints apply:
There are no limits to the number of objects that can be stored in a bucket. Performance does not vary based on the number of buckets used. Store all objects within a single bucket or organize them across several buckets.
Buckets cannot be nested; buckets cannot be created within other buckets.
Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup routine that runs less often.
To create a bucket, authenticate with an account that has a valid AWS Access Key ID and is registered with Amazon S3. Anonymous requests are never allowed to create buckets.
bucketName - The name of the bucket to create.
All buckets in Amazon S3 share a single namespace;
ensure the bucket is given a unique name.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.@Deprecated Bucket createBucket(String bucketName, Region region) throws SdkClientException, AmazonServiceException
AmazonS3.createBucket(String) instead.Creates a new Amazon S3 bucket with the specified name in the specified Amazon S3 region.
Every object stored in Amazon S3 is contained within a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, any name can be used for objects. However, bucket names must be unique across all of Amazon S3.
Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
To conform with DNS requirements, the following constraints apply:
There are no limits to the number of objects that can be stored in a bucket. Performance does not vary based on the number of buckets used. Store all objects within a single bucket or organize them across several buckets.
Buckets cannot be nested; buckets cannot be created within other buckets.
Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup routine that runs less often.
To create a bucket, authenticate with an account that has a valid AWS Access Key ID and is registered with Amazon S3. Anonymous requests are never allowed to create buckets.
bucketName - The name of the bucket to create.region - The Amazon S3 region in which to create the new bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.Region,
AWS API Documentation@Deprecated Bucket createBucket(String bucketName, String region) throws SdkClientException, AmazonServiceException
AmazonS3.createBucket(String) instead.
Creates a new Amazon S3 bucket with the specified name in the specified
Amazon S3 region. This method is provided for non-standard cases;
use AmazonS3.createBucket(String, Region) and pass in a Region
enumeration value in standard cases.
Every object stored in Amazon S3 is contained within a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, any name can be used for objects. However, bucket names must be unique across all of Amazon S3.
Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
To conform with DNS requirements, the following constraints apply:
There are no limits to the number of objects that can be stored in a bucket. Performance does not vary based on the number of buckets used. Store all objects within a single bucket or organize them across several buckets.
Buckets cannot be nested; buckets cannot be created within other buckets.
Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup routine that runs less often.
To create a bucket, authenticate with an account that has a valid AWS Access Key ID and is registered with Amazon S3. Anonymous requests are never allowed to create buckets.
bucketName - The name of the bucket to create.region - The Amazon S3 region in which to create the new bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.Region,
AWS API DocumentationAccessControlList getObjectAcl(String bucketName, String key) throws SdkClientException, AmazonServiceException
Gets the AccessControlList (ACL) for the specified object in Amazon S3.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
bucketName - The name of the bucket containing the object whose ACL is
being retrieved.key - The key of the object within the specified bucket whose ACL is
being retrieved.AccessControlList for the specified Amazon S3 object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObjectAcl(String, String, String),
AWS API DocumentationAccessControlList getObjectAcl(String bucketName, String key, String versionId) throws SdkClientException, AmazonServiceException
Gets the AccessControlList (ACL) for the specified object
with the specified version in Amazon S3.
Each version of an object has its own associated
ACL.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
bucketName - The name of the bucket containing the object whose ACL is
being retrieved.key - The key of the object within the specified bucket whose ACL is
being retrieved.versionId - The version ID of the object version whose ACL is being
retrieved.AccessControlList for the specified Amazon S3 object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObjectAcl(String, String),
AWS API DocumentationAccessControlList getObjectAcl(GetObjectAclRequest getObjectAclRequest) throws SdkClientException, AmazonServiceException
Gets the AccessControlList (ACL) for the specified object in Amazon S3.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
getObjectAclRequest - the request object containing all the information needed for retrieving
the object ACL.AccessControlList for the specified Amazon S3 object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObjectAcl(String, String, String),
AWS API Documentationvoid setObjectAcl(String bucketName, String key, AccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the AccessControlList for the specified object in Amazon S3.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
When constructing a custom AccessControlList,
callers typically retrieve
the existing AccessControlList for an object (
AmazonS3Client.getObjectAcl(String, String)), modify it as
necessary, and then use this method to upload the new ACL.
bucketName - The name of the bucket containing the object whose ACL is
being set.key - The key of the object within the specified bucket whose ACL is
being set.acl - The new AccessControlList for the specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setObjectAcl(String, String, CannedAccessControlList),
AmazonS3.setObjectAcl(String, String, String, AccessControlList),
AmazonS3.setObjectAcl(String, String, String, CannedAccessControlList),
AWS API Documentationvoid setObjectAcl(String bucketName, String key, CannedAccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the CannedAccessControlList for the specified object in
Amazon S3 using one
of the pre-configured CannedAccessControlLists.
A CannedAccessControlList
provides a quick way to configure an object or bucket with commonly used
access control policies.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
bucketName - The name of the bucket containing the object whose ACL is
being set.key - The key of the object within the specified bucket whose ACL is
being set.acl - The new pre-configured CannedAccessControlList for the
specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setObjectAcl(String, String, AccessControlList),
AmazonS3.setObjectAcl(String, String, String, AccessControlList),
AmazonS3.setObjectAcl(String, String, String, CannedAccessControlList),
AWS API Documentationvoid setObjectAcl(String bucketName, String key, String versionId, AccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the CannedAccessControlList for the specified object
with the specified version in Amazon S3.
Each version of an object has its own associated
ACL.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
When constructing a custom AccessControlList, callers typically retrieve
the existing AccessControlList for an object (
AmazonS3Client.getObjectAcl(String, String)), modify it as
necessary, and then use this method to upload the new ACL.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
bucketName - The name of the bucket containing the object whose ACL is
being set.key - The key of the object within the specified bucket whose ACL is
being set.versionId - The version ID of the object version whose ACL is being set.acl - The new AccessControlList for the specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setObjectAcl(String, String, AccessControlList),
AmazonS3.setObjectAcl(String, String, CannedAccessControlList),
AmazonS3.setObjectAcl(String, String, String, CannedAccessControlList),
AWS API Documentationvoid setObjectAcl(String bucketName, String key, String versionId, CannedAccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the CannedAccessControlList for the specified object with the specified
version ID in Amazon S3 using one of the pre-configured
CannedAccessControlLists.
A CannedAccessControlList
provides a quick way to configure an object or bucket with commonly used
access control policies.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy and each version of an object has its own associated ACL. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
bucketName - The name of the bucket containing the object whose ACL is
being set.key - The key of the object within the specified bucket whose ACL is
being set.versionId - The version ID of the object version whose ACL is being set.acl - The new pre-configured CannedAccessControlList for the
specified object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setObjectAcl(String, String, AccessControlList),
AmazonS3.setObjectAcl(String, String, CannedAccessControlList),
AmazonS3.setObjectAcl(String, String, String, AccessControlList),
AWS API Documentationvoid setObjectAcl(SetObjectAclRequest setObjectAclRequest) throws SdkClientException, AmazonServiceException
AccessControlList for the specified Amazon S3 object
with an optional version ID.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
When constructing a custom AccessControlList, callers
typically retrieve the existing AccessControlList for a
bucket (AmazonS3Client.getObjectAcl(String, String)), modify it
as necessary, and then use this method to upload the new ACL.
setObjectAclRequest - The request object containing the S3 object to modify and the
ACL to set.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AccessControlList getBucketAcl(String bucketName) throws SdkClientException, AmazonServiceException
Gets the AccessControlList (ACL) for the specified Amazon S3 bucket.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
bucketName - The name of the bucket whose ACL is being retrieved.AccessControlList for the specified S3 bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.FASPConnectionInfo getBucketFaspConnectionInfo(String bucketName) throws SdkClientException, AmazonServiceException
Gets the FASP Connection Info for a particular bucket.
Each bucket COS has associated FASP connection information this will return Access Key & Secret, along with an ATS Endpoint
bucketName - The name of the bucket whose FASPConnectionInfo is being retrieved. FASPConnectionInfo for the specified S3 bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.FASPConnectionInfo getBucketFaspConnectionInfo(GetBucketFaspConnectionInfoRequest getBucketFASPConnectionInfoRequest) throws SdkClientException, AmazonServiceException
Gets the FASP Connection Info for a particular bucket.
Each bucket COS has associated FASP connection information this will return Access Key & Secret, along with an ATS Endpoint
getBucketFASPConnectionInfoRequest - The request containing the name of the bucket whose FASPConnectionInfo is
being retrieved. FASPConnectionInfo for the specified S3 bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void setBucketAcl(SetBucketAclRequest setBucketAclRequest) throws SdkClientException, AmazonServiceException
AccessControlList for the specified Amazon S3 bucket.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
When constructing a custom AccessControlList, callers
typically retrieve the existing AccessControlList for a
bucket ( AmazonS3Client.getBucketAcl(String)), modify it as
necessary, and then use this method to upload the new ACL.
setBucketAclRequest - The request object containing the bucket to modify and the ACL
to set.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AccessControlList getBucketAcl(GetBucketAclRequest getBucketAclRequest) throws SdkClientException, AmazonServiceException
AccessControlList (ACL) for the specified Amazon S3
bucket.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
getBucketAclRequest - The request containing the name of the bucket whose ACL is
being retrieved.AccessControlList for the specified S3 bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void setBucketAcl(String bucketName, AccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the AccessControlList for the specified Amazon S3 bucket.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
When constructing a custom AccessControlList, callers typically retrieve
the existing AccessControlList for a bucket (
AmazonS3Client.getBucketAcl(String)), modify it as necessary, and
then use this method to upload the new ACL.
bucketName - The name of the bucket whose ACL is being set.acl - The new AccessControlList for the specified bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setBucketAcl(String, CannedAccessControlList),
AWS API Documentationvoid setBucketAcl(String bucketName, CannedAccessControlList acl) throws SdkClientException, AmazonServiceException
Sets the CannedAccessControlList for the specified Amazon S3 bucket using one of
the pre-configured CannedAccessControlLists.
A CannedAccessControlList
provides a quick way to configure an object or bucket with commonly used
access control policies.
Each bucket and object in Amazon S3 has an ACL that defines its access control policy. When a request is made, Amazon S3 authenticates the request using its standard authentication procedure and then checks the ACL to verify the sender was granted access to the bucket or object. If the sender is approved, the request proceeds. Otherwise, Amazon S3 returns an error.
bucketName - The name of the bucket whose ACL is being set.acl - The pre-configured CannedAccessControlLists to set for the
specified bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setBucketAcl(String, AccessControlList),
AWS API DocumentationObjectMetadata getObjectMetadata(String bucketName, String key) throws SdkClientException, AmazonServiceException
Gets the metadata for the specified Amazon S3 object without actually fetching the object itself. This is useful in obtaining only the object metadata, and avoids wasting bandwidth on fetching the object data.
The object metadata contains information such as content type, content disposition, etc., as well as custom user metadata that can be associated with an object in Amazon S3.
bucketName - The name of the bucket containing the object's whose metadata
is being retrieved.key - The key of the object whose metadata is being retrieved.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObjectMetadata(GetObjectMetadataRequest),
AWS API DocumentationObjectMetadata getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest) throws SdkClientException, AmazonServiceException
Gets the metadata for the specified Amazon S3 object without actually fetching the object itself. This is useful in obtaining only the object metadata, and avoids wasting bandwidth on fetching the object data.
The object metadata contains information such as content type, content disposition, etc., as well as custom user metadata that can be associated with an object in Amazon S3.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
getObjectMetadataRequest - The request object specifying the bucket, key and optional
version ID of the object whose metadata is being retrieved.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObjectMetadata(String, String),
AWS API DocumentationS3Object getObject(String bucketName, String key) throws SdkClientException, AmazonServiceException
Gets the object stored in Amazon S3 under the specified bucket and key.
Be extremely careful when using this method; the returned Amazon S3 object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be reused until the user finishes reading the data and closes the stream. Also note that if not all data is read from the stream then the SDK will abort the underlying connection, this may have a negative impact on performance. Therefore:
GetObjectRequest.setRange(long, long) to request only the bytes you need)
To get an object from Amazon S3, the caller must have
Permission.Read access to the object.
If the object fetched is publicly readable, it can also read it by pasting its URL into a browser.
For more advanced options (such as downloading only a range of an
object's content, or placing constraints on when the object should be
downloaded) callers can use AmazonS3.getObject(GetObjectRequest).
If you are accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket containing the desired object.key - The key under which the desired object is stored.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObject(GetObjectRequest),
AmazonS3.getObject(GetObjectRequest, File),
AWS API DocumentationS3Object getObject(GetObjectRequest getObjectRequest) throws SdkClientException, AmazonServiceException
Gets the object stored in Amazon S3 under the specified bucket and
key.
Returns null if the specified constraints weren't met.
Be extremely careful when using this method; the returned Amazon S3 object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be reused until the user finishes reading the data and closes the stream. Also note that if not all data is read from the stream then the SDK will abort the underlying connection, this may have a negative impact on performance. Therefore:
GetObjectRequest.setRange(long, long) to request only the bytes you need)
To get an object from Amazon S3, the caller must have Permission.Read
access to the object.
If the object fetched is publicly readable, it can also read it by pasting its URL into a browser.
When specifying constraints in the request object, the client needs to be
prepared to handle this method returning null
if the provided constraints aren't met when Amazon S3 receives the request.
If the advanced options provided in GetObjectRequest aren't needed,
use the simpler AmazonS3.getObject(String bucketName, String key) method.
If you are accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObject in interface S3DirectSpigetObjectRequest - The request object containing all the options on how to
download the object.null if constraints were specified but not met.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObject(String, String),
AmazonS3.getObject(GetObjectRequest, File),
AWS API DocumentationObjectMetadata getObject(GetObjectRequest getObjectRequest, File destinationFile) throws SdkClientException, AmazonServiceException
Gets the object metadata for the object stored
in Amazon S3 under the specified bucket and key,
and saves the object contents to the
specified file.
Returns null if the specified constraints weren't met.
Instead of
using AmazonS3.getObject(GetObjectRequest),
use this method to ensure that the underlying
HTTP stream resources are automatically closed as soon as possible.
The Amazon S3 clients handles immediate storage of the object
contents to the specified file.
To get an object from Amazon S3, the caller must have Permission.Read
access to the object.
If the object fetched is publicly readable, it can also read it by pasting its URL into a browser.
When specifying constraints in the request object, the client needs to be
prepared to handle this method returning null
if the provided constraints aren't met when Amazon S3 receives the request.
If you are accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
getObject in interface S3DirectSpigetObjectRequest - The request object containing all the options on how to
download the Amazon S3 object content.destinationFile - Indicates the file (which might already exist) where
to save the object content being downloading from Amazon S3.null if constraints were specified but not met.SdkClientException - If any errors are encountered in the client while making the
request, handling the response, or writing the incoming data
from S3 to the specified destination file.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getObject(String, String),
AmazonS3.getObject(GetObjectRequest),
AWS API DocumentationString getObjectAsString(String bucketName, String key) throws AmazonServiceException, SdkClientException
Retrieves and decodes the contents of an S3 object to a String.
bucketName - The name of the bucket containing the object to retrieve.key - The key of the object to retrieve.AmazonServiceExceptionSdkClientExceptionvoid deleteBucket(DeleteBucketRequest deleteBucketRequest) throws SdkClientException, AmazonServiceException
Deletes the specified bucket. All objects (and all object versions, if versioning was ever enabled) in the bucket must be deleted before the bucket itself can be deleted.
Only the owner of a bucket can delete it, regardless of the bucket's access control policy (ACL).
deleteBucketRequest - The request object containing all options for deleting an Amazon S3
bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.deleteBucket(String),
AWS API Documentationvoid deleteBucket(String bucketName) throws SdkClientException, AmazonServiceException
Deletes the specified bucket. All objects (and all object versions, if versioning was ever enabled) in the bucket must be deleted before the bucket itself can be deleted.
Only the owner of a bucket can delete it, regardless of the bucket's access control policy.
bucketName - The name of the bucket to delete.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.deleteBucket(String),
AWS API DocumentationPutObjectResult putObject(PutObjectRequest putObjectRequest) throws SdkClientException, AmazonServiceException
Uploads a new object to the specified Amazon S3 bucket. The
PutObjectRequest contains all the details of the request,
including the bucket to upload to, the key the object will be uploaded
under, and the file or input stream containing the data to upload.
Amazon S3 never stores partial objects; if during this call an exception wasn't thrown, the entire object was stored.
If you are uploading or accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
Depending on whether a file or input stream is being uploaded, this method has slightly different behavior.
When uploading a file:
When uploading directly from an input stream:
If versioning is enabled for the specified bucket, this operation will
never overwrite an existing object with the same key, but will keep the
existing object as an older version until that version is explicitly
deleted (see AmazonS3.deleteVersion(String, String, String).
If versioning is not enabled, this operation will overwrite an existing object with the same key; Amazon S3 will store the last write request. Amazon S3 does not provide object locking. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored. However, a single object will be stored with the final write request.
When specifying a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's region. For example, if specifying a Europe (EU) region constraint for a bucket, all of that bucket's objects are stored in the EU region.
The specified bucket must already exist and the caller must have
Permission.Write permission to the bucket to upload an object.
putObject in interface S3DirectSpiputObjectRequest - The request object containing all the parameters to upload a
new object to Amazon S3.PutObjectResult object containing the information
returned by Amazon S3 for the newly created object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.putObject(String, String, File),
AmazonS3.putObject(String, String, InputStream, ObjectMetadata),
AWS API DocumentationPutObjectResult putObject(String bucketName, String key, File file) throws SdkClientException, AmazonServiceException
Uploads the specified file to Amazon S3 under the specified bucket and key name.
Amazon S3 never stores partial objects; if during this call an exception wasn't thrown, the entire object was stored.
If you are uploading or accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
The client automatically computes a checksum of the file. Amazon S3 uses checksums to validate the data in each file.
Using the file extension, Amazon S3 attempts to determine the correct content type and content disposition to use for the object.
If versioning is enabled for the specified bucket,
this operation will never overwrite an existing object
with the same key, but will keep the existing object as an
older version
until that version is
explicitly deleted (see
AmazonS3.deleteVersion(String, String, String).
If versioning is not enabled, this operation will overwrite an existing object with the same key; Amazon S3 will store the last write request. Amazon S3 does not provide object locking. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored. However, a single object will be stored with the final write request.
When specifying a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's region. For example, if specifying a Europe (EU) region constraint for a bucket, all of that bucket's objects are stored in EU region.
The specified bucket must already exist and the caller must have
Permission.Write permission to the bucket to upload an object.
bucketName - The name of an existing bucket, to which you have
Permission.Write permission.key - The key under which to store the specified file.file - The file containing the data to be uploaded to Amazon S3.PutObjectResult object containing the information
returned by Amazon S3 for the newly created object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.putObject(PutObjectRequest),
AmazonS3.putObject(String, String, InputStream, ObjectMetadata),
AWS API DocumentationPutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata) throws SdkClientException, AmazonServiceException
Uploads the specified input stream and object metadata to Amazon S3 under the specified bucket and key name.
Amazon S3 never stores partial objects; if during this call an exception wasn't thrown, the entire object was stored.
If you are uploading or accessing AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
The client automatically computes a checksum of the file. This checksum is verified against another checksum that is calculated once the data reaches Amazon S3, ensuring the data has not corrupted in transit over the network.
Using the file extension, Amazon S3 attempts to determine the correct content type and content disposition to use for the object.
Content length must be specified before data can be uploaded to Amazon S3. If the caller doesn't provide it, the library will make a best effort to compute the content length by buffer the contents of the input stream into the memory because Amazon S3 explicitly requires that the content length be sent in the request headers before any of the data is sent. Please note that this operation is not guaranteed to succeed.
When using an BufferedInputStream as data source,
please remember to use a buffer of size no less than
RequestClientOptions.DEFAULT_STREAM_BUFFER_SIZE
while initializing the BufferedInputStream.
This is to ensure that the SDK can correctly mark and reset the stream with
enough memory buffer during signing and retries.
If versioning is enabled for the specified bucket, this operation will
never overwrite an existing object at the same key, but instead will keep
the existing object around as an older version until that version is
explicitly deleted (see
AmazonS3.deleteVersion(String, String, String).
If versioning is not enabled, this operation will overwrite an existing object with the same key; Amazon S3 will store the last write request. Amazon S3 does not provide object locking. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored. However, a single object will be stored with the final write request.
When specifying a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's region. For example, if specifying a Europe (EU) region constraint for a bucket, all of that bucket's objects are stored in EU region.
The specified bucket must already exist and the caller must have
Permission.Write permission to the bucket to upload an object.
bucketName - The name of an existing bucket, to which you have
Permission.Write permission.key - The key under which to store the specified file.input - The input stream containing the data to be uploaded to Amazon
S3.metadata - Additional metadata instructing Amazon S3 how to handle the
uploaded data (e.g. custom user metadata, hooks for specifying
content type, etc.).PutObjectResult object containing the information
returned by Amazon S3 for the newly created object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.putObject(String, String, File),
AmazonS3.putObject(PutObjectRequest),
AWS API DocumentationPutObjectResult putObject(String bucketName, String key, String content) throws AmazonServiceException, SdkClientException
Encodes a String into the contents of an S3 object.
String will be encoded to bytes with UTF-8 encoding.
bucketName - The name of the bucket to place the new object in.key - The key of the object to create.content - The String to encodeAmazonServiceExceptionSdkClientExceptionCopyObjectResult copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey) throws SdkClientException, AmazonServiceException
Copies a source object to a new destination in Amazon S3.
By default, all object metadata for the source object except
server-side-encryption, storage-class and
website-redirect-location are copied to the new destination
object, unless new object metadata in the specified
CopyObjectRequest is provided.
The Amazon S3 Acccess Control List (ACL) is not copied to the new
object. The new object will have the default Amazon S3 ACL,
CannedAccessControlList.Private, unless one is explicitly
provided in the specified CopyObjectRequest.
To copy an object, the caller's account must have read access to the source object and write access to the destination bucket
This method only exposes the basic options for copying an Amazon S3
object. Additional options are available by calling the
AmazonS3Client.copyObject(CopyObjectRequest) method, including
conditional constraints for copying objects, setting ACLs, overwriting
object metadata, etc.
If you are copying AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
sourceBucketName - The name of the bucket containing the source object to copy.sourceKey - The key in the source bucket under which the source object is stored.destinationBucketName - The name of the bucket in which the new object will be
created. This can be the same name as the source bucket's.destinationKey - The key in the destination bucket under which the new object
will be created.CopyObjectResult object containing the information
returned by Amazon S3 for the newly created object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.copyObject(CopyObjectRequest),
AWS API DocumentationCopyObjectResult copyObject(CopyObjectRequest copyObjectRequest) throws SdkClientException, AmazonServiceException
Copies a source object to a new destination in Amazon S3.
By default, all object metadata for the source object except
server-side-encryption, storage-class and
website-redirect-location are copied to the new destination
object, unless new object metadata in the specified
CopyObjectRequest is provided.
The Amazon S3 Acccess Control List (ACL) is not copied to the new
object. The new object will have the default Amazon S3 ACL,
CannedAccessControlList.Private, unless one is explicitly
provided in the specified CopyObjectRequest.
To copy an object, the caller's account must have read access to the source object and write access to the destination bucket.
If constraints are specified in the CopyObjectRequest (e.g.
CopyObjectRequest.setMatchingETagConstraints(List)) and are not
satisfied when Amazon S3 receives the request, this method returns
null. This method returns a non-null result under all other
circumstances.
This method exposes all the advanced options for copying an Amazon S3
object. For simple needs, use the
AmazonS3Client.copyObject(String, String, String, String) method.
If you are copying AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
copyObjectRequest - The request object containing all the options for copying an
Amazon S3 object.CopyObjectResult object containing the information
returned by Amazon S3 about the newly created object, or
null if constraints were specified that weren't met
when Amazon S3 attempted to copy the object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.copyObject(String, String, String, String),
AWS API DocumentationCopyPartResult copyPart(CopyPartRequest copyPartRequest) throws SdkClientException, AmazonServiceException
If constraints are specified in the CopyPartRequest
(e.g.
CopyPartRequest.setMatchingETagConstraints(List))
and are not satisfied when Amazon S3 receives the
request, this method returns null.
This method returns a non-null result under all other
circumstances.
If you are copying AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
copyPart in interface S3DirectSpicopyPartRequest - The request object containing all the options for copying an
Amazon S3 object.CopyPartResult object containing the information
returned by Amazon S3 about the newly created object, or null if
constraints were specified that weren't met when Amazon S3 attempted
to copy the object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.copyObject(CopyObjectRequest),
AmazonS3Client.initiateMultipartUpload(InitiateMultipartUploadRequest),
AWS API Documentationvoid deleteObject(String bucketName, String key) throws SdkClientException, AmazonServiceException
Deletes the specified object in the specified bucket. Once deleted, the object can only be restored if versioning was enabled when the object was deleted.
If attempting to delete an object that does not exist, Amazon S3 returns a success message instead of an error message.
bucketName - The name of the Amazon S3 bucket containing the object to
delete.key - The key of the object to delete.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.deleteObject(DeleteObjectRequest),
AWS API Documentationvoid deleteObject(DeleteObjectRequest deleteObjectRequest) throws SdkClientException, AmazonServiceException
Deletes the specified object in the specified bucket. Once deleted, the object can only be restored if versioning was enabled when the object was deleted.
If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.
deleteObjectRequest - The request object containing all options for deleting an Amazon S3
object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.deleteObject(String, String),
AWS API DocumentationDeleteObjectsResult deleteObjects(DeleteObjectsRequest deleteObjectsRequest) throws SdkClientException, AmazonServiceException
In some cases, some objects will be successfully deleted, while some
attempts will cause an error. If any object in the request cannot be
deleted, this method throws a MultiObjectDeleteException with
details of the error.
deleteObjectsRequest - The request object containing all options for deleting
multiple objects.MultiObjectDeleteException - if one or more of the objects couldn't be deleted.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteVersion(String bucketName, String key, String versionId) throws SdkClientException, AmazonServiceException
Deletes a specific version of the specified object in the specified bucket. Once deleted, there is no method to restore or undelete an object version. This is the only way to permanently delete object versions that are protected by versioning.
Deleting an object version is permanent and irreversible. It is a privileged operation that only the owner of the bucket containing the version can perform.
Users can only delete a version of an object if versioning is enabled
for the bucket.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.
bucketName - The name of the Amazon S3 bucket containing the object to
delete.key - The key of the object to delete.versionId - The version of the object to delete.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteVersion(DeleteVersionRequest deleteVersionRequest) throws SdkClientException, AmazonServiceException
Deletes a specific version of an object in the specified bucket. Once deleted, there is no method to restore or undelete an object version. This is the only way to permanently delete object versions that are protected by versioning.
Deleting an object version is permanent and irreversible. It is a privileged operation that only the owner of the bucket containing the version can perform.
Users can only delete a version of an object if versioning is enabled
for the bucket.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest).
If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.
deleteVersionRequest - The request object containing all options for deleting a
specific version of an Amazon S3 object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.BucketVersioningConfiguration getBucketVersioningConfiguration(String bucketName) throws SdkClientException, AmazonServiceException
Returns the versioning configuration for the specified bucket.
A bucket's versioning configuration can be in one of three possible states:
BucketVersioningConfiguration.OFF
BucketVersioningConfiguration.ENABLED
BucketVersioningConfiguration.SUSPENDED
By default, new buckets are in the
off state. Once versioning is
enabled for a bucket the status can never be reverted to
off.
The versioning configuration of a bucket has different implications for
each operation performed on that bucket or for objects within that
bucket. For example, when versioning is enabled a PutObject
operation creates a unique object version-id for the object being uploaded. The
The PutObject API guarantees that, if versioning is enabled for a bucket at
the time of the request, the new object can only be permanently deleted
using a DeleteVersion operation. It can never be overwritten.
Additionally, the PutObject API guarantees that,
if versioning is enabled for a bucket the request,
no other object will be overwritten by that request.
Refer to the documentation sections for each API for information on how
versioning status affects the semantics of that particular API.
Amazon S3 is eventually consistent. It can take time for the versioning status of a bucket to be propagated throughout the system.
bucketName - The bucket whose versioning configuration will be retrieved.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest),
AmazonS3.getBucketVersioningConfiguration(GetBucketVersioningConfigurationRequest),
AWS API DocumentationBucketVersioningConfiguration getBucketVersioningConfiguration(GetBucketVersioningConfigurationRequest getBucketVersioningConfigurationRequest) throws SdkClientException, AmazonServiceException
Returns the versioning configuration for the specified bucket.
A bucket's versioning configuration can be in one of three possible states:
BucketVersioningConfiguration.OFF
BucketVersioningConfiguration.ENABLED
BucketVersioningConfiguration.SUSPENDED
By default, new buckets are in the
off state. Once versioning is
enabled for a bucket the status can never be reverted to
off.
The versioning configuration of a bucket has different implications for
each operation performed on that bucket or for objects within that
bucket. For example, when versioning is enabled a PutObject
operation creates a unique object version-id for the object being uploaded. The
The PutObject API guarantees that, if versioning is enabled for a bucket at
the time of the request, the new object can only be permanently deleted
using a DeleteVersion operation. It can never be overwritten.
Additionally, the PutObject API guarantees that,
if versioning is enabled for a bucket the request,
no other object will be overwritten by that request.
Refer to the documentation sections for each API for information on how
versioning status affects the semantics of that particular API.
Amazon S3 is eventually consistent. It can take time for the versioning status of a bucket to be propagated throughout the system.
getBucketVersioningConfigurationRequest - The request object for retrieving the bucket versioning configuration.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest),
AmazonS3.getBucketVersioningConfiguration(String),
AWS API Documentationvoid setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest) throws SdkClientException, AmazonServiceException
Sets the versioning configuration for the specified bucket.
A bucket's versioning configuration can be in one of three possible states:
BucketVersioningConfiguration.OFF
BucketVersioningConfiguration.ENABLED
BucketVersioningConfiguration.SUSPENDED
By default, new buckets are in the
off state. Once versioning is
enabled for a bucket the status can never be reverted to
off.
Objects created before versioning was enabled or when versioning is
suspended will be given the default null version ID (see
Constants.NULL_VERSION_ID). Note that the
null version ID is a valid version ID and is not the
same as not having a version ID.
The versioning configuration of a bucket has different implications for
each operation performed on that bucket or for objects within that
bucket. For example, when versioning is enabled a PutObject
operation creates a unique object version-id for the object being uploaded. The
The PutObject API guarantees that, if versioning is enabled for a bucket at
the time of the request, the new object can only be permanently deleted
using a DeleteVersion operation. It can never be overwritten.
Additionally, the PutObject API guarantees that,
if versioning is enabled for a bucket the request,
no other object will be overwritten by that request.
Refer to the documentation sections for each API for information on how
versioning status affects the semantics of that particular API.
Amazon S3 is eventually consistent. It can take time for the versioning status of a bucket to be propagated throughout the system.
setBucketVersioningConfigurationRequest - The request object containing all options for setting the
bucket versioning configuration.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3.getBucketVersioningConfiguration(String),
AWS API DocumentationBucketLifecycleConfiguration getBucketLifecycleConfiguration(String bucketName)
bucketName - The name of the bucket for which to retrieve lifecycle
configuration.AmazonS3.getBucketLifecycleConfiguration(GetBucketLifecycleConfigurationRequest),
AWS API DocumentationBucketLifecycleConfiguration getBucketLifecycleConfiguration(GetBucketLifecycleConfigurationRequest getBucketLifecycleConfigurationRequest)
getBucketLifecycleConfigurationRequest - The request object for retrieving the bucket lifecycle
configuration.AmazonS3.getBucketLifecycleConfiguration(String),
AWS API Documentationvoid setBucketLifecycleConfiguration(String bucketName, BucketLifecycleConfiguration bucketLifecycleConfiguration)
bucketName - The name of the bucket for which to set the lifecycle
configuration.bucketLifecycleConfiguration - The new lifecycle configuration for this bucket, which
completely replaces any existing configuration.void setBucketLifecycleConfiguration(SetBucketLifecycleConfigurationRequest setBucketLifecycleConfigurationRequest)
setBucketLifecycleConfigurationRequest - The request object containing all options for setting the
bucket lifecycle configuration.void deleteBucketLifecycleConfiguration(String bucketName)
bucketName - The name of the bucket for which to remove the lifecycle
configuration.void deleteBucketLifecycleConfiguration(DeleteBucketLifecycleConfigurationRequest deleteBucketLifecycleConfigurationRequest)
deleteBucketLifecycleConfigurationRequest - The request object containing all options for removing the
bucket lifecycle configuration.BucketCrossOriginConfiguration getBucketCrossOriginConfiguration(String bucketName)
bucketName - The name of the bucket for which to retrieve cross origin
configuration.AmazonS3.getBucketCrossOriginConfiguration(GetBucketCrossOriginConfigurationRequest),
AWS API DocumentationBucketCrossOriginConfiguration getBucketCrossOriginConfiguration(GetBucketCrossOriginConfigurationRequest getBucketCrossOriginConfigurationRequest)
getBucketCrossOriginConfigurationRequest - The request object for retrieving the bucket cross origin
configuration.AmazonS3.getBucketCrossOriginConfiguration(String),
AWS API Documentationvoid setBucketCrossOriginConfiguration(String bucketName, BucketCrossOriginConfiguration bucketCrossOriginConfiguration)
bucketName - The name of the bucket for which to retrieve cross origin
configuration.bucketCrossOriginConfiguration - The new cross origin configuration for this bucket, which
completely replaces any existing configuration.void setBucketCrossOriginConfiguration(SetBucketCrossOriginConfigurationRequest setBucketCrossOriginConfigurationRequest)
setBucketCrossOriginConfigurationRequest - The request object containing all options for setting the
bucket cross origin configuration.void deleteBucketCrossOriginConfiguration(String bucketName)
bucketName - The name of the bucket for which to retrieve cross origin
configuration.void deleteBucketCrossOriginConfiguration(DeleteBucketCrossOriginConfigurationRequest deleteBucketCrossOriginConfigurationRequest)
deleteBucketCrossOriginConfigurationRequest - The request object containing all options for deleting the
bucket cross origin configuration.BucketWebsiteConfiguration getBucketWebsiteConfiguration(String bucketName) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
This operation requires the S3:GetBucketWebsite permission.
By default, only the bucket owner can read the bucket website
configuration. However, bucket owners can allow other users to read the
website configuration by writing a bucket policy granting them the
S3:GetBucketWebsite permission.
bucketName - The name of the bucket whose website configuration is being
retrieved.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.BucketWebsiteConfiguration getBucketWebsiteConfiguration(GetBucketWebsiteConfigurationRequest getBucketWebsiteConfigurationRequest) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting. html.
This operation requires the S3:GetBucketWebsite permission.
By default, only the bucket owner can read the bucket website
configuration. However, bucket owners can allow other users to read the
website configuration by writing a bucket policy granting them the
S3:GetBucketWebsite permission.
getBucketWebsiteConfigurationRequest - The request object for retrieving the bucket website configuration.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void setBucketWebsiteConfiguration(String bucketName, BucketWebsiteConfiguration configuration) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
This operation requires the S3:PutBucketWebsite permission.
By default, only the bucket owner can configure the website attached to a
bucket. However, bucket owners can allow other users to set the website
configuration by writing a bucket policy granting them the
S3:PutBucketWebsite permission.
bucketName - The name of the bucket whose website configuration is being
set.configuration - The configuration describing how the specified bucket will
serve web requests (i.e. default index page, error page).SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void setBucketWebsiteConfiguration(SetBucketWebsiteConfigurationRequest setBucketWebsiteConfigurationRequest) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting. html.
This operation requires the S3:PutBucketWebsite permission.
By default, only the bucket owner can configure the website attached to a
bucket. However, bucket owners can allow other users to set the website
configuration by writing a bucket policy granting them the
S3:PutBucketWebsite permission.
setBucketWebsiteConfigurationRequest - The request object containing the name of the bucket whose
website configuration is being updated, and the new website
configuration values.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteBucketWebsiteConfiguration(String bucketName) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
This operation requires the S3:DeleteBucketWebsite
permission. By default, only the bucket owner can delete the website
configuration attached to a bucket. However, bucket owners can grant
other users permission to delete the website configuration by writing a
bucket policy granting them the S3:DeleteBucketWebsite
permission.
bucketName - The name of the bucket whose website configuration is being
deleted.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteBucketWebsiteConfiguration(DeleteBucketWebsiteConfigurationRequest deleteBucketWebsiteConfigurationRequest) throws SdkClientException, AmazonServiceException
For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting. html.
This operation requires the S3:DeleteBucketWebsite
permission. By default, only the bucket owner can delete the website
configuration attached to a bucket. However, bucket owners can grant
other users permission to delete the website configuration by writing a
bucket policy granting them the S3:DeleteBucketWebsite
permission.
deleteBucketWebsiteConfigurationRequest - The request object specifying the name of the bucket whose
website configuration is to be deleted.SdkClientException - If any errors are encountered on the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.URL generatePresignedUrl(String bucketName, String key, Date expiration) throws SdkClientException
Returns a pre-signed URL for accessing an Amazon S3 resource.
Pre-signed URLs allow clients to form a URL for an Amazon S3 resource, and then sign it with the current AWS security credentials. The pre-signed URL can be shared to other users, allowing access to the resource without providing an account's AWS security credentials.
Pre-signed URLs are useful in many situations where AWS security credentials aren't available from the client that needs to make the actual request to Amazon S3.
For example, an application may need remote users to upload files to the application owner's Amazon S3 bucket, but doesn't need to ship the AWS security credentials with the application. A pre-signed URL to PUT an object into the owner's bucket can be generated from a remote location with the owner's AWS security credentials, then the pre-signed URL can be passed to the end user's application to use.
If you are generating presigned url for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket containing the desired object.key - The key in the specified bucket under which the desired object
is stored.expiration - The time at which the returned pre-signed URL will expire.SdkClientException - If there were any problems pre-signing the request for the
specified S3 object.AmazonS3.generatePresignedUrl(String, String, Date, HttpMethod),
AmazonS3.generatePresignedUrl(GeneratePresignedUrlRequest)URL generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethod method) throws SdkClientException
Returns a pre-signed URL for accessing an Amazon S3 resource.
Pre-signed URLs allow clients to form a URL for an Amazon S3 resource, and then sign it with the current AWS security credentials. The pre-signed URL can be shared to other users, allowing access to the resource without providing an account's AWS security credentials.
Pre-signed URLs are useful in many situations where AWS security credentials aren't available from the client that needs to make the actual request to Amazon S3.
For example, an application may need remote users to upload files to the application owner's Amazon S3 bucket, but doesn't need to ship the AWS security credentials with the application. A pre-signed URL to PUT an object into the owner's bucket can be generated from a remote location with the owner's AWS security credentials, then the pre-signed URL can be passed to the end user's application to use.
If you are generating presigned url for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
bucketName - The name of the bucket containing the desired object.key - The key in the specified bucket under which the desired object
is stored.expiration - The time at which the returned pre-signed URL will expire.method - The HTTP method verb to use for this URLSdkClientException - If there were any problems pre-signing the request for the
specified S3 object.AmazonS3.generatePresignedUrl(String, String, Date),
AmazonS3.generatePresignedUrl(GeneratePresignedUrlRequest)URL generatePresignedUrl(GeneratePresignedUrlRequest generatePresignedUrlRequest) throws SdkClientException
Returns a pre-signed URL for accessing an Amazon S3 resource.
Pre-signed URLs allow clients to form a URL for an Amazon S3 resource, and then sign it with the current AWS security credentials. The pre-signed URL can be shared to other users, allowing access to the resource without providing an account's AWS security credentials.
Pre-signed URLs are useful in many situations where AWS security credentials aren't available from the client that needs to make the actual request to Amazon S3.
For example, an application may need remote users to upload files to the application owner's Amazon S3 bucket, but doesn't need to ship the AWS security credentials with the application. A pre-signed URL to PUT an object into the owner's bucket can be generated from a remote location with the owner's AWS security credentials, then the pre-signed URL can be passed to the end user's application to use.
Note that presigned URLs cannot be used to upload an object with an attached policy, as described in this blog post. That method is only suitable for POSTs from HTML forms by browsers.
If you are generating presigned url for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
generatePresignedUrlRequest - The request object containing all the options for generating a
pre-signed URL (bucket name, key, expiration date, etc).SdkClientException - If there were any problems pre-signing the request for the
Amazon S3 resource.AmazonS3.generatePresignedUrl(String, String, Date),
AmazonS3.generatePresignedUrl(String, String, Date, HttpMethod)InitiateMultipartUploadResult initiateMultipartUpload(InitiateMultipartUploadRequest request) throws SdkClientException, AmazonServiceException
AmazonS3.uploadPart(UploadPartRequest) requests. You also include this
upload ID in the final request to either complete, or abort the multipart
upload request.
Note: After you initiate a multipart upload and upload one or more parts, you must either complete or abort the multipart upload in order to stop getting charged for storage of the uploaded parts. Once you complete or abort the multipart upload Amazon S3 will release the stored parts and stop charging you for their storage.
If you are initiating a multipart upload for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
initiateMultipartUpload in interface S3DirectSpirequest - The InitiateMultipartUploadRequest object that specifies all
the parameters of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.UploadPartResult uploadPart(UploadPartRequest request) throws SdkClientException, AmazonServiceException
Your UploadPart request must include an upload ID and a part number. The upload ID is the ID returned by Amazon S3 in response to your Initiate Multipart Upload request. Part number can be any number between 1 and 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being uploaded. If you upload a new part using the same part number that was specified in uploading a previous part, the previously uploaded part is overwritten.
To ensure data is not corrupted traversing the network, specify the Content-MD5 header in the Upload Part request. Amazon S3 checks the part data against the provided MD5 value. If they do not match, Amazon S3 returns an error.
When you upload a part, the returned UploadPartResult contains an ETag property. You should record this ETag property value and the part number. After uploading all parts, you must send a CompleteMultipartUpload request. At that time Amazon S3 constructs a complete object by concatenating all the parts you uploaded, in ascending order based on the part numbers. The CompleteMultipartUpload request requires you to send all the part numbers and the corresponding ETag values.
Note: After you initiate a multipart upload and upload one or more parts, you must either complete or abort the multipart upload in order to stop getting charged for storage of the uploaded parts. Once you complete or abort the multipart upload Amazon S3 will release the stored parts and stop charging you for their storage.
If you are performing upload part for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
When supplying an InputStream using UploadPartRequest.withInputStream(InputStream) or UploadPartRequest.setInputStream(InputStream), the stream will only be
closed by the client if UploadPartRequest.isLastPart() is true. If this is not the last part, the stream will be left open.
uploadPart in interface S3DirectSpirequest - The UploadPartRequest object that specifies all the parameters
of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.PartListing listParts(ListPartsRequest request) throws SdkClientException, AmazonServiceException
This method must include the upload ID, returned by the
AmazonS3.initiateMultipartUpload(InitiateMultipartUploadRequest)
operation. This request returns a maximum of 1000 uploaded parts by
default. You can restrict the number of parts returned by specifying the
MaxParts property on the ListPartsRequest. If your multipart upload
consists of more parts than allowed in the ListParts response, the
response returns a IsTruncated field with value true, and a
NextPartNumberMarker property. In subsequent ListParts request you can
include the PartNumberMarker property and set its value to the
NextPartNumberMarker property value from the previous response.
request - The ListPartsRequest object that specifies all the parameters
of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void abortMultipartUpload(AbortMultipartUploadRequest request) throws SdkClientException, AmazonServiceException
abortMultipartUpload in interface S3DirectSpirequest - The AbortMultipartUploadRequest object that specifies all the
parameters of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request) throws SdkClientException, AmazonServiceException
You first upload all parts using the
AmazonS3.uploadPart(UploadPartRequest) method. After successfully
uploading all individual parts of an upload, you call this operation to
complete the upload. Upon receiving this request, Amazon S3 concatenates
all the parts in ascending order by part number to create a new object.
In the CompleteMultipartUpload request, you must provide the parts list.
For each part in the list, you provide the part number and the ETag
header value, returned after that part was uploaded.
Processing of a CompleteMultipartUpload request may take several minutes to complete.
If you are perfoming a complete multipart upload for AWS KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
completeMultipartUpload in interface S3DirectSpirequest - The CompleteMultipartUploadRequest object that specifies all
the parameters of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.MultipartUploadListing listMultipartUploads(ListMultipartUploadsRequest request) throws SdkClientException, AmazonServiceException
This operation returns at most 1,000 multipart uploads in the response by default. The number of multipart uploads can be further limited using the MaxUploads property on the request parameter. If there are additional multipart uploads that satisfy the list criteria, the response will contain an IsTruncated property with the value set to true. To list the additional multipart uploads use the KeyMarker and UploadIdMarker properties on the request parameters.
request - The ListMultipartUploadsRequest object that specifies all the
parameters of this operation.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.S3ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)
Response metadata is only cached for a limited period of time. Use this method to retrieve the response metadata as soon as possible after executing a request.
request - The originally executed request.null if none is available.void restoreObject(RestoreObjectRequest request) throws AmazonServiceException
request - The request object containing all the options for restoring an
Amazon S3 object.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.restoreObject(String, String, int)void restoreObject(String bucketName, String key, int expirationInDays) throws AmazonServiceException
bucketName - The name of an existing bucket.key - The key under which to store the specified file.expirationInDays - The number of days after which the object will expire.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.restoreObject(RestoreObjectRequest)boolean doesObjectExist(String bucketName, String objectName) throws AmazonServiceException, SdkClientException
bucketName - Name of bucket that presumably contains objectobjectName - Name of object that has to be checkedAmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.void setBucketProtectionConfiguration(SetBucketProtectionConfigurationRequest setBucketProtectionRequest) throws SdkClientException, AmazonServiceException
setBucketProtectionRequest - The request object containing all options for setting the
bucket protection configurationSdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.BucketProtectionConfiguration getBucketProtection(String bucketName) throws SdkClientException, AmazonServiceException
bucketName - The bucket whose protection configuration will be retrieved.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.BucketProtectionConfiguration getBucketProtectionConfiguration(GetBucketProtectionConfigurationRequest getBucketProtectionRequest) throws SdkClientException, AmazonServiceException
getBucketProtectionRequest - The request object for retrieving the bucket protection configuration.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void setBucketProtection(String bucketName, BucketProtectionConfiguration protectionConfiguration) throws SdkClientException, AmazonServiceException
bucketName - The name of the bucket for which to set protection configurationbucketProtection - The new protection configuration for this bucket, which
completely replaces any existing configuration.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void addLegalHold(String bucketName, String key, String legalHoldId) throws SdkClientException, AmazonServiceException
bucketName - The name of the Amazon S3 bucket containing the object to
add a legal hold to.key - The key of the object to add a legal hold to.legalHoldId - The id of the legal hold to add.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void addLegalHold(AddLegalHoldRequest addLegalHoldRequest) throws SdkClientException, AmazonServiceException
addLegalHoldRequest - The request object containing all options for adding a legal hold to an
object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.addLegalHold(String, String, String)ListLegalHoldsResult listLegalHolds(String bucketName, String key) throws SdkClientException, AmazonServiceException
bucketName - The name of the bucket containing the object.key - The name of the object to list legal holds for.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.ListLegalHoldsResult listLegalHolds(ListLegalHoldsRequest listLegalHoldsRequest) throws SdkClientException, AmazonServiceException
listLegalHoldsRequest - The request object containing all options for listing the
legal holds for a specified object in a specified bucket.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteLegalHold(String bucketName, String key, String legalHoldId) throws SdkClientException, AmazonServiceException
bucketName - The name of the Amazon S3 bucket containing the object to
delete a legal hold from.key - The key of the object to delete a legal hold from.legalHoldId - The id of the legal hold to delete.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void deleteLegalHold(DeleteLegalHoldRequest deleteLegalHoldRequest) throws SdkClientException, AmazonServiceException
deleteLegalHoldRequest - The request object containing all options for deleting a legal hold from an
object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.deleteLegalHold(String, String, String)void extendObjectRetention(String bucketName, String key, Long additionalRetentionPeriod, Long extendRetentionFromCurrentTime, Date newRetentionExpirationDate, Long newRetentionPeriod) throws SdkClientException, AmazonServiceException
bucketName - The name of the Amazon S3 bucket containing the object to
delete a legal hold from.key - The key of the object to delete a legal hold from.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.void extendObjectRetention(ExtendObjectRetentionRequest extendObjectRetentionRequest) throws SdkClientException, AmazonServiceException
extendObjectRetentionRequest - The request object containing all options for extending the retention period
of a protected object.SdkClientException - If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException - If any errors occurred in Amazon S3 while processing the
request.AmazonS3Client.deleteLegalHold(String, String, String)void shutdown()
Region getRegion()
String getRegionName()
URL getUrl(String bucketName, String key)
If the object identified by the given bucket and key has public read
permissions (ex: CannedAccessControlList.PublicRead), then this
URL can be directly accessed to retrieve the object's data.
bucketName - The name of the bucket containing the object whose URL is
being requested.key - The key under which the object whose URL is being requested is
stored.AmazonS3Waiters waiters()
Copyright © 2020. All rights reserved.