Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.amazonaws.services.s3
Interface AmazonS3

All Known Implementing Classes:
  AmazonS3Client

    public interface AmazonS3

Provides the client for accessing the Amazon S3 web service.

For more information about Amazon S3, please see http://aws.amazon.com/s3

Method Summary
`void` | `changeObjectStorageClass(String bucketName, String key, StorageClass newStorageClass)` Changes the Amazon S3 storage class for a specified object.
`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.
`Bucket` | `createBucket(CreateBucketRequest createBucketRequest)` Creates a new Amazon S3 bucket with the specified name, in the default (US) region - `Region.US_Standard`.
`Bucket` | `createBucket(String bucketName)` Creates a new Amazon S3 bucket with the specified name, in the default (US) region - `Region.US_Standard`.
`Bucket` | `createBucket(String bucketName, Region region)` Creates a new Amazon S3 bucket with the specified name, in the specified Amazon S3 region.
`Bucket` | `createBucket(String bucketName, String region)` Creates a new Amazon S3 bucket with the specified name, in the specified Amazon S3 region.
`void` | `deleteBucket(DeleteBucketRequest deleteBucketRequest)` Deletes the specified bucket.
`void` | `deleteBucket(String bucketName)` Deletes the specified bucket.
`void` | `deleteBucketPolicy(String bucketName)` Deletes the policy associated with 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.
`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)` Checks if the specified bucket exists.
`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 GET URL to download the S3 object in the specified bucket under the specified key.
`URL` | `generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethod method)` Returns a pre-signed GET URL to download the S3 object in the specified bucket under the specified key.
`AccessControlList` | `getBucketAcl(String bucketName)` Retrieves the AccessControlList for the specified Amazon S3 bucket.
`String` | `getBucketLocation(String bucketName)` Returns the geographical region where Amazon S3 stores the specified bucket.
`BucketLoggingConfiguration` | `getBucketLoggingConfiguration(String bucketName)` Returns the logging configuration for the specified bucket.
`BucketNotificationConfiguration` | `getBucketNotificationConfiguration(String bucketName)` Returns the notification configuration for the specified bucket.
`BucketPolicy` | `getBucketPolicy(String bucketName)` Retrieves the policy for the specified bucket.
`BucketVersioningConfiguration` | `getBucketVersioningConfiguration(String bucketName)` Returns the versioning configuration for the specified bucket.
`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(String bucketName, String key)` Retrieves the AccessControlList for the specified object in Amazon S3.
`AccessControlList` | `getObjectAcl(String bucketName, String key, String versionId)` Retrieves the AccessControlList for the specified object at the specified version in Amazon S3.
`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.
`Owner` | `getS3AccountOwner()` Returns the current owner of the AWS account being used by the authenticated sender of the request.
`List<Bucket>` | `listBuckets()` Returns a list of all Amazon S3 buckets owned by the authenticated sender of the request.
`List<Bucket>` | `listBuckets(ListBucketsRequest listBucketsRequest)` Returns a list of all Amazon S3 buckets owned by the authenticated sender of the request.
`ObjectListing` | `listNextBatchOfObjects(ObjectListing previousObjectListing)` Provides an easy way to continue a truncated object listing 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.
`VersionListing` | `listVersions(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.
`void` | `setBucketAcl(String bucketName, AccessControlList acl)` Set the AccessControlList for the specified Amazon S3 bucket.
`void` | `setBucketAcl(String bucketName, CannedAccessControlList acl)` Set the AccessControlList for the specified Amazon S3 bucket using one of the pre-configured CannedAccessControlLists.
`void` | `setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest setBucketLoggingConfigurationRequest)` Sets the logging configuration for the specified bucket.
`void` | `setBucketNotificationConfiguration(String bucketName, BucketNotificationConfiguration bucketNotificationConfiguration)` Sets the notification configuration for the specified bucket.
`void` | `setBucketPolicy(String bucketName, String policyText)` Sets the policy associated with the specified bucket.
`void` | `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)` Sets the versioning configuration for the specified bucket.
`void` | `setEndpoint(String endpoint)` Overrides the default endpoint for this client.
`void` | `setObjectAcl(String bucketName, String key, AccessControlList acl)` Set the AccessControlList for the specified object in Amazon S3.
`void` | `setObjectAcl(String bucketName, String key, CannedAccessControlList acl)` Set the AccessControlList for the specified object in Amazon S3 using one of the pre-configured CannedAccessControlLists.
`void` | `setObjectAcl(String bucketName, String key, String versionId, AccessControlList acl)` Set the AccessControlList for the specified object at the specified version in Amazon S3.
`void` | `setObjectAcl(String bucketName, String key, String versionId, CannedAccessControlList acl)` Set the AccessControlList for the specified object at the specified version ID in Amazon S3 using one of the pre-configured CannedAccessControlLists.

Method Detail

### setEndpoint

    void setEndpoint(String endpoint)

  Overrides the default endpoint for this client. Callers can use this method to control which AWS region they want to work with.

  Callers can pass in the endpoint (ex: "s3.amazonaws.com") or a full URL, including the protocol (ex: "https://s3.amazonaws.com"). If the protocol is not specified, the default protocol (HTTPS) from this client's `ClientConfiguration` will be used.

  Parameters:
    `endpoint` - The endpoint (ex: "s3.amazonaws.com") or the full URL, including the protocol (ex: "https://s3.amazonaws.com"), of the region-specific AWS endpoint this client will communicate with.
  Throws:
    `IllegalArgumentException` - If the specified endpoint is not a valid URL endpoint.

### changeObjectStorageClass

    void changeObjectStorageClass(String bucketName,
                                  String key,
                                  StorageClass newStorageClass)
                                  throws AmazonClientException,
                                         AmazonServiceException

  Changes the Amazon S3 storage class for a specified object. Amazon S3 offers multiple storage classes for customer's different needs.

  Note that when changing the storage class for an object in a bucket with versioning enabled, the current version of the object will persist in its current storage class, and a new, latest version will be created and stored in the new storage class.

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### listObjects

    ObjectListing listObjects(String bucketName)
                              throws AmazonClientException,
                                     AmazonServiceException

  Returns a list of summary information about the objects in the specified buckets. List results are always returned in lexicographic (alphabetical) order.

  Since 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.

  List performance is not substantially affected by the total number of keys in a bucket.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket to list.
  Returns:
    A listing of the objects in the specified bucket, along with any other associated information such as common prefixes (if a delimiter was specified), the original request parameters, etc.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#listObjects(String bucketName, String prefix)}`, `AmazonS3Client#listObjects(ListObjectsRequest listObjectsRequest)}`

### listObjects

    ObjectListing listObjects(String bucketName,
                              String prefix)
                              throws AmazonClientException,
                                     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.

  Since 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:

  - "foo/bar/baz"
  - "foo/bar/bash"
  - "foo/bar/bang"
  - "foo/boo"
  If calling `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.

  List performance is not substantially affected by the total number of keys in a bucket, nor by the presence or absence of any additional request parameters.

  Parameters:
    `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.
  Returns:
    A listing of the objects in the specified bucket, along with any other associated information such as common prefixes (if a delimiter was specified), the original request parameters, etc.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#listObjects(String bucketName)}`, `AmazonS3Client#listObjects(ListObjectsRequest listObjectsRequest)}`

### listObjects

    ObjectListing listObjects(ListObjectsRequest listObjectsRequest)
                              throws AmazonClientException,
                                     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.

  Since 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:

  - "foo/bar/baz"
  - "foo/bar/bash"
  - "foo/bar/bang"
  - "foo/boo"
  If calling `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.

  List performance is not substantially affected by the total number of keys in a bucket, nor by the presence or absence of any additional request parameters.

  Parameters:
    `listObjectsRequest` - The request object containing all options for listing the objects in a specified bucket.
  Returns:
    A listing of the objects in the specified bucket, along with any other associated information such as common prefixes (if a delimiter was specified), the original request parameters, etc.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#listObjects(String bucketName)}`, `AmazonS3Client#listObjects(String bucketName, String prefix)}`

### listNextBatchOfObjects

    ObjectListing listNextBatchOfObjects(ObjectListing previousObjectListing)
                                         throws AmazonClientException,
                                                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.

  Parameters:
    `previousObjectListing` - The previous truncated `ObjectListing`. If a non-truncated `ObjectListing` is passed in, an empty `ObjectListing` will be returned without ever contacting Amazon S3.
  Returns:
    The next set of `ObjectListing` results, beginning immediately after the last result in the specified previous `ObjectListing`.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client.listObjects(String)`, `AmazonS3Client.listObjects(String, String)`, `AmazonS3Client.listObjects(ListObjectsRequest)`

### listVersions

    VersionListing listVersions(String bucketName,
                                String prefix)
                                throws AmazonClientException,
                                       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.

  Since 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 `listNextBatchOfVersions(VersionListing)` as an easy way to get the next page of results.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `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.
  Returns:
    A listing of the versions in the specified bucket, along with any other associated information and original request parameters.
  Throws:
    `AmazonClientException` - 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.

### listNextBatchOfVersions

    VersionListing listNextBatchOfVersions(VersionListing previousVersionListing)
                                           throws AmazonClientException,
                                                  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 `ObjectListing.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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `previousVersionListing` - The previous truncated `VersionListing`. If a non-truncated `VersionListing` is passed in, an empty `VersionListing` will be returned without ever contacting Amazon S3.
  Returns:
    The next set of `VersionListing` results, beginning immediately after the last result in the specified previous `VersionListing`.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client.listVersions(String, String)`, `AmazonS3Client.listVersions(ListVersionsRequest)`

### listVersions

    VersionListing listVersions(String bucketName,
                                String prefix,
                                String keyMarker,
                                String versionIdMarker,
                                String delimiter,
                                Integer maxResults)
                                throws AmazonClientException,
                                       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.

  Since 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 callers additional calls are needed to get more results. Callers are encouraged to use `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:

  - "foo/bar/baz"
  - "foo/bar/bash"
  - "foo/bar/bang"
  - "foo/boo"
  If calling `listVersions` with a `prefix` value of "foo/" and a `delimiter` value of "/" on this bucket, a `VersionListing` is returned that contains:
  - all the versions for one key ("foo/boo")
  - one entry in the common prefixes list ("foo/bar/")

  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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose versions are to be listed.
    `prefix` - An optional parameter restricting the response to keys which 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 `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 `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.
  Returns:
    A listing of the versions in the specified bucket, along with any other associated information such as common prefixes (if a delimiter was specified), the original request parameters, etc.
  Throws:
    `AmazonClientException` - 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.

### listVersions

    VersionListing listVersions(ListVersionsRequest listVersionsRequest)
                                throws AmazonClientException,
                                       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 (i.e. alphabetically from a-Z) and versions are sorted from most recent to least recent. Both versions with data and delete markers are included in the results.

  Since 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. Callers should always check the `VersionListing.isTruncated()` method to determine if the returned listing is complete, or if callers need to make additional calls to get more results. The key and version ID marker parameters allow callers to specify where to start the version listing. Callers are encouraged to use `listNextBatchOfVersions(VersionListing)` as an easy way to get the next page of results.

  The delimiter parameter allows groups of keys that share a prefix terminated by a special delimiter to be rolled-up by that common prefix in the returned listing. This allows applications to organize and browse their keys hierarchically, much like how you would organize your files into directories in a file system. These common prefixes can be retrieved through the `VersionListing.getCommonPrefixes()` method.

  For example, consider a bucket that contains the keys:

  - "foo/bar/baz"
  - "foo/bar/bash"
  - "foo/bar/bang"
  - "foo/boo"

  If you call listVersions with prefix="foo/" and delimiter="/" on this bucket, you will get an S3VersionListing back that contains:

  - all the versions for one key ("foo/boo")
  - one entry in the common prefixes list ("foo/bar/")

  If you want to see deeper into the virtual hierarchy, you can make another call to listVersions setting the prefix parameter to any interesting common prefix to list the individual versions under that prefix.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `listVersionsRequest` - The request object containing all options for listing the versions in a specified bucket.
  Returns:
    A listing of the versions in the specified bucket, along with any other associated information such as common prefixes (if a delimiter was specified), the original request parameters, etc.
  Throws:
    `AmazonClientException` - 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.

### getS3AccountOwner

    Owner getS3AccountOwner()
                            throws AmazonClientException,
                                   AmazonServiceException

  Returns the current owner of the AWS account being used by the authenticated sender of the request.

  The caller must authenticate with a valid AWS Access Key ID that is registered with Amazon S3.

  Returns:
    The account of the authenticated sender
  Throws:
    `AmazonClientException` - 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.

### doesBucketExist

    boolean doesBucketExist(String bucketName)
                            throws AmazonClientException,
                                   AmazonServiceException

  Checks if the specified bucket exists. Amazon S3 buckets are named in a global namespace; use this method to determine if a specified bucket name already exists, and therefore can't be used to create a new bucket.

  Parameters:
    `bucketName` - The name of the bucket to check.
  Returns:
    A value of `true` if the specified bucket exists in Amazon S3; a value of `false` if there is no bucket in Amazon S3 with that name.
  Throws:
    `AmazonClientException` - 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.

### listBuckets

    List<Bucket> listBuckets()
                             throws AmazonClientException,
                                    AmazonServiceException

  Returns a list of all Amazon S3 buckets owned by the authenticated sender of the request.

  You must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and you cannot list buckets that you did not create.

  Returns:
    A list of all of the Amazon S3 buckets owned by the authenticated sender of the request.
  Throws:
    `AmazonClientException` - 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.

### listBuckets

    List<Bucket> listBuckets(ListBucketsRequest listBucketsRequest)
                             throws AmazonClientException,
                                    AmazonServiceException

  Returns a list of all Amazon S3 buckets owned by the authenticated sender of the request.

  You must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and you cannot list buckets that you did not create.

  Parameters:
    `request` - The request containing all of the options regating the listing of buckets.
  Returns:
    A list of all of the Amazon S3 buckets owned by the authenticated sender of the request.
  Throws:
    `AmazonClientException` - 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.

### getBucketLocation

    String getBucketLocation(String bucketName)
                             throws AmazonClientException,
                                    AmazonServiceException

  Returns the geographical region where Amazon S3 stores the specified bucket.

  To view the location constraint of a bucket, you must be the bucket owner.

  Callers can use `Region.fromValue(String)` to get the Region enum value, but should be prepared to handle IllegalArgumentExceptions if the passed in value is not a known region value.

  Region enum values are not returned directly from this method for forwards compatibility reasons. As new Amazon S3 regions are added, they would cause runtime errors when trying to instantiate Region enum values from them.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket to look up. This must be a bucket that you own.
  Returns:
    The location of the specified Amazon S3 bucket.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `Region`

### createBucket

    Bucket createBucket(CreateBucketRequest createBucketRequest)
                        throws AmazonClientException,
                               AmazonServiceException

  Creates a new Amazon S3 bucket with the specified name, in the default (US) region - `Region.US_Standard`.

  Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be unique across all of Amazon S3.

  Buckets are similar to Internet domain names. Just as Amazon is the only owner of the domain name Amazon.com, only one person or organization can own a bucket within Amazon S3. Once you create a uniquely named bucket in Amazon S3, you can organize and name the objects within the bucket in any way you like and the bucket will remain yours for as long as you like and as long as you have the Amazon S3 account.

  The similarities between buckets and domain names is not a coincidence - there is a direct mapping between Amazon S3 buckets and subdomains of s3.amazonaws.com. Objects stored in Amazon S3 are addressable using the REST API under the domain bucketname.s3.amazonaws.com. For example, if the object homepage.html is stored in the Amazon S3 bucket mybucket its address would be http://mybucket.s3.amazonaws.com/homepage.html.

  To conform with DNS requirements, the following constraints apply:

  - Bucket names should not contain underscores (_)
  - Bucket names should be between 3 and 63 characters long
  - Bucket names should not end with a dash
  - Bucket names cannot contain two, adjacent periods
  - Bucket names cannot contain dashes next to periods (e.g., "my-.bucket.com" and "my.-bucket" are invalid)
  - Bucket names cannot contain uppercase characters

  There is no limit to the number of objects that can be stored in a bucket and no variation in performance when using many buckets or just a few. You can store all of your objects in a single bucket or organize them across several buckets.

  Buckets cannot be nested, meaning buckets cannot be created within buckets.

  The high availability engineering of Amazon S3 is focused on get, put, list, and delete operations. Because bucket operations work against a centralized, global resource space, it is not appropriate to make bucket create or delete calls on the high availability code path of your application. It is better to create or delete buckets in a separate initialization or setup routine that you run less often.

  To create a bucket, you must 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.

  Parameters:
    `createBucketRequest` - The request object containing all options for creating an S3 bucket.
  Returns:
    The newly created bucket.
  Throws:
    `AmazonClientException` - 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.

### createBucket

    Bucket createBucket(String bucketName)
                        throws AmazonClientException,
                               AmazonServiceException

  Creates a new Amazon S3 bucket with the specified name, in the default (US) region - `Region.US_Standard`.

  Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be unique across all of Amazon S3.

  Buckets are similar to Internet domain names. Just as Amazon is the only owner of the domain name Amazon.com, only one person or organization can own a bucket within Amazon S3. Once you create a uniquely named bucket in Amazon S3, you can organize and name the objects within the bucket in any way you like and the bucket will remain yours for as long as you like and as long as you have the Amazon S3 account.

  The similarities between buckets and domain names is not a coincidence - there is a direct mapping between Amazon S3 buckets and subdomains of s3.amazonaws.com. Objects stored in Amazon S3 are addressable using the REST API under the domain bucketname.s3.amazonaws.com. For example, if the object homepage.html is stored in the Amazon S3 bucket mybucket its address would be http://mybucket.s3.amazonaws.com/homepage.html.

  To conform with DNS requirements, the following constraints apply:

  - Bucket names should not contain underscores (_)
  - Bucket names should be between 3 and 63 characters long
  - Bucket names should not end with a dash
  - Bucket names cannot contain two, adjacent periods
  - Bucket names cannot contain dashes next to periods (e.g., "my-.bucket.com" and "my.-bucket" are invalid)
  - Bucket names cannot contain uppercase characters

  There is no limit to the number of objects that can be stored in a bucket and no variation in performance when using many buckets or just a few. You can store all of your objects in a single bucket or organize them across several buckets.

  Buckets cannot be nested, meaning buckets cannot be created within buckets.

  The high availability engineering of Amazon S3 is focused on get, put, list, and delete operations. Because bucket operations work against a centralized, global resource space, it is not appropriate to make bucket create or delete calls on the high availability code path of your application. It is better to create or delete buckets in a separate initialization or setup routine that you run less often.

  To create a bucket, you must 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.

  Parameters:
    `bucketName` - The name of the bucket to create.
  Returns:
    The newly created bucket.
  Throws:
    `AmazonClientException` - 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.

### createBucket

    Bucket createBucket(String bucketName,
                        Region region)
                        throws AmazonClientException,
                               AmazonServiceException

  Creates a new Amazon S3 bucket with the specified name, in the specified Amazon S3 region.

  Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be globally unique across all of Amazon S3.

  Buckets are similar to Internet domain names. Just as Amazon is the only owner of the domain name Amazon.com, only one person or organization can own a bucket within Amazon S3. Once you create a uniquely named bucket in Amazon S3, you can organize and name the objects within the bucket in any way you like and the bucket will remain yours for as long as you like and as long as you have the Amazon S3 account.

  The similarities between buckets and domain names is not a coincidence - there is a direct mapping between Amazon S3 buckets and subdomains of s3.amazonaws.com. Objects stored in Amazon S3 are addressable using the REST API under the domain bucketname.s3.amazonaws.com. For example, if the object homepage.html is stored in the Amazon S3 bucket mybucket its address would be http://mybucket.s3.amazonaws.com/homepage.html.

  To conform with DNS requirements, the following constraints apply:

  - Bucket names should not contain underscores (_)
  - Bucket names should be between 3 and 63 characters long
  - Bucket names should not end with a dash
  - Bucket names cannot contain two, adjacent periods
  - Bucket names cannot contain dashes next to periods (e.g., "my-.bucket.com" and "my.-bucket" are invalid)
  - Bucket names cannot contain uppercase characters

  There is no limit to the number of objects that can be stored in a bucket and no variation in performance when using many buckets or just a few. You can store all of your objects in a single bucket or organize them across several buckets.

  Buckets cannot be nested, meaning buckets cannot be created within buckets.

  The high availability engineering of Amazon S3 is focused on get, put, list, and delete operations. Because bucket operations work against a centralized, global resource space, it is not appropriate to make bucket create or delete calls on the high availability code path of your application. It is better to create or delete buckets in a separate initialization or setup routine that you run less often.

  To create a bucket, you must 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.

  Parameters:
    `bucketName` - The name of the bucket to create. Bucket names are globally unique, so
    `region` - The Amazon S3 region in which to create the new bucket.
  Returns:
    The newly created bucket.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `Region`

### createBucket

    Bucket createBucket(String bucketName,
                        String region)
                        throws AmazonClientException,
                               AmazonServiceException

  Creates a new Amazon S3 bucket with the specified name, in the specified Amazon S3 region. Callers are encouraged to use `createBucket(String, Region)` and pass in the `Region` enum, but this method is provided for non-standard cases.

  Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be globally unique across all of Amazon S3.

  Buckets are similar to Internet domain names. Just as Amazon is the only owner of the domain name Amazon.com, only one person or organization can own a bucket within Amazon S3. Once you create a uniquely named bucket in Amazon S3, you can organize and name the objects within the bucket in any way you like and the bucket will remain yours for as long as you like and as long as you have the Amazon S3 account.

  The similarities between buckets and domain names is not a coincidence - there is a direct mapping between Amazon S3 buckets and subdomains of s3.amazonaws.com. Objects stored in Amazon S3 are addressable using the REST API under the domain bucketname.s3.amazonaws.com. For example, if the object homepage.html is stored in the Amazon S3 bucket mybucket its address would be http://mybucket.s3.amazonaws.com/homepage.html.

  To conform with DNS requirements, the following constraints apply:

  - Bucket names should not contain underscores (_)
  - Bucket names should be between 3 and 63 characters long
  - Bucket names should not end with a dash
  - Bucket names cannot contain two, adjacent periods
  - Bucket names cannot contain dashes next to periods (e.g., "my-.bucket.com" and "my.-bucket" are invalid)
  - Bucket names cannot contain uppercase characters

  There is no limit to the number of objects that can be stored in a bucket and no variation in performance when using many buckets or just a few. You can store all of your objects in a single bucket or organize them across several buckets.

  Buckets cannot be nested, meaning buckets cannot be created within buckets.

  The high availability engineering of Amazon S3 is focused on get, put, list, and delete operations. Because bucket operations work against a centralized, global resource space, it is not appropriate to make bucket create or delete calls on the high availability code path of your application. It is better to create or delete buckets in a separate initialization or setup routine that you run less often.

  To create a bucket, you must 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.

  Parameters:
    `bucketName` - The name of the bucket to create. Bucket names are globally unique, so
    `region` - The Amazon S3 region in which to create the new bucket.
  Returns:
    The newly created bucket.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `Region`

### getObjectAcl

    AccessControlList getObjectAcl(String bucketName,
                                   String key)
                                   throws AmazonClientException,
                                          AmazonServiceException

  Retrieves 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.

  Parameters:
    `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.
  Returns:
    The AccessControlList for the specified S3 object.
  Throws:
    `AmazonClientException` - 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.

### getObjectAcl

    AccessControlList getObjectAcl(String bucketName,
                                   String key,
                                   String versionId)
                                   throws AmazonClientException,
                                          AmazonServiceException

  Retrieves the AccessControlList for the specified object at 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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `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.
  Returns:
    The AccessControlList for the specified S3 object.
  Throws:
    `AmazonClientException` - 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.

### setObjectAcl

    void setObjectAcl(String bucketName,
                      String key,
                      AccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set 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.

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### setObjectAcl

    void setObjectAcl(String bucketName,
                      String key,
                      CannedAccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set the AccessControlList for the specified object in Amazon S3 using one of the pre-configured CannedAccessControlLists. CannedAccessControlLists are 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.

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### setObjectAcl

    void setObjectAcl(String bucketName,
                      String key,
                      String versionId,
                      AccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set the AccessControlList for the specified object at 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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### setObjectAcl

    void setObjectAcl(String bucketName,
                      String key,
                      String versionId,
                      CannedAccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set the AccessControlList for the specified object at the specified version ID in Amazon S3 using one of the pre-configured CannedAccessControlLists. CannedAccessControlLists are 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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### getBucketAcl

    AccessControlList getBucketAcl(String bucketName)
                                   throws AmazonClientException,
                                          AmazonServiceException

  Retrieves 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.

  Parameters:
    `bucketName` - The name of the bucket whose ACL is being retrieved.
  Returns:
    The AccessControlList for the specified S3 bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketAcl

    void setBucketAcl(String bucketName,
                      AccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set 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.

  Parameters:
    `bucketName` - The name of the bucket whose ACL is being set.
    `acl` - The new AccessControlList for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketAcl

    void setBucketAcl(String bucketName,
                      CannedAccessControlList acl)
                      throws AmazonClientException,
                             AmazonServiceException

  Set the AccessControlList for the specified Amazon S3 bucket using one of the pre-configured CannedAccessControlLists. CannedAccessControlLists are 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.

  Parameters:
    `bucketName` - The name of the bucket whose ACL is being set.
    `acl` - The pre-configured CannedAccessControlList to set for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### getObjectMetadata

    ObjectMetadata getObjectMetadata(String bucketName,
                                     String key)
                                     throws AmazonClientException,
                                            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.

  Parameters:
    `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.
  Returns:
    All S3 object metadata for the specified object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)}`

### getObjectMetadata

    ObjectMetadata getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)
                                     throws AmazonClientException,
                                            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.

  See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Parameters:
    `getObjectMetadataRequest` - The request object specifying the bucket, key and optional version ID of the object whose metadata is being retrieved.
  Returns:
    All S3 object metadata for the specified object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#getObjectMetadata(String bucketName, String key)}`

### getObject

    S3Object getObject(String bucketName,
                       String key)
                       throws AmazonClientException,
                              AmazonServiceException

  Gets the object stored in Amazon S3 under the specified bucket and key.

  Callers should be very careful when using this method; the returned S3Object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be closed until the user finishes reading the data and closes the stream. Callers should therefore:

  - Use the data from the input stream in S3Object as soon as possible,
  - Close the input stream in S3Object as soon as possible.
  If callers do not follow these rules, the client can run out of resources if allocating too many open, but unused, HTTP connections.

  To get an object from Amazon S3, the caller must have `Permission.Read` access to the object.

  If the object you're fetching is publicly readable, you 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 `getObject(GetObjectRequest)`.

  Parameters:
    `bucketName` - The name of the bucket containing the desired object.
    `key` - The key under which the desired object is stored.
  Returns:
    The object stored in Amazon S3 in the specified bucket and key.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#getObject(GetObjectRequest getObjectRequest)}`, `AmazonS3#getObject(GetObjectRequest getObjectRequest, File destinationFile)}`

### getObject

    S3Object getObject(GetObjectRequest getObjectRequest)
                       throws AmazonClientException,
                              AmazonServiceException

  Gets the object stored in Amazon S3 under the specified bucket and key. Returns `null` if the specified constraints weren't met.

  Callers should be very careful when using this method; the returned S3Object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be closed until the user finishes reading the data and closes the stream. Callers should therefore:

  - Use the data from the input stream in S3Object as soon as possible,
  - Close the input stream in S3Object as soon as possible.

  If callers do not follow those rules, then the client can run out of resources if allocating too many open, but unused, HTTP connections.

  To get an object from Amazon S3, the caller must have `Permission.Read` access to the object.

  If the object you're fetching is publicly readable, you 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 in `GetObjectRequest` aren't needed, use the simpler `getObject(String bucketName, String key)` method.

  Parameters:
    `getObjectRequest` - The request object containing all the options on how to download the object.
  Returns:
    The object stored in Amazon S3 in the specified bucket and key. Returns `null` if constraints were specified but not met.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#getObject(String bucketName, String key)}`, `AmazonS3#getObject(GetObjectRequest getObjectRequest, File destinationFile)}`

### getObject

    ObjectMetadata getObject(GetObjectRequest getObjectRequest,
                             File destinationFile)
                             throws AmazonClientException,
                                    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.

  Use this method, instead of `getObject(GetObjectRequest)`, to ensure that the underlying HTTP stream resources are automatically closed as soon as possible. The S3 client will handle immediately storing 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 you're fetching is publicly readable, you 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.

  Parameters:
    `getObjectRequest` - The request object containing all the options on how to download the S3 object content.
    `destinationFile` - The file (which may or may not already exist) indicating where to save the object content being downloading from Amazon S3.
  Returns:
    All S3 object metadata for the specified object. Returns `null` if constraints were specified but not met.
  Throws:
    `AmazonClientException` - If any errors are encountered on 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.
  See Also:
    `AmazonS3#getObject(String bucketName, String key)}`, `AmazonS3#getObject(GetObjectRequest getObjectRequest)}`

### deleteBucket

    void deleteBucket(DeleteBucketRequest deleteBucketRequest)
                      throws AmazonClientException,
                             AmazonServiceException

  Deletes the specified bucket. All objects (and all 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.

  Parameters:
    `deleteBucketRequest` - The request object containing all options for delete an S3 bucket.
  Throws:
    `AmazonClientException` - 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.

### deleteBucket

    void deleteBucket(String bucketName)
                      throws AmazonClientException,
                             AmazonServiceException

  Deletes the specified bucket. All objects (and all 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.

  Parameters:
    `bucketName` - The name of the bucket to delete.
  Throws:
    `AmazonClientException` - 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.

### putObject

    PutObjectResult putObject(PutObjectRequest putObjectRequest)
                              throws AmazonClientException,
                                     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.

  Depending on whether a file or input stream is being uploaded, this method has slightly different behavior.

  When uploading a file:

  - 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.
  - The file extension is used to try and automatically determine the correct content type and content disposition to use for the object.

  When uploading directly from an input stream:

  - Callers should be careful to set the correct content type in the metadata object before directly sending a stream. Unlike when uploading from files, content types from input streams cannot be automatically determined. If the caller doesn't explicitly set the content type, it will not be set in Amazon S3.
  - Content length must be specified before data can be uploaded to Amazon S3. If the caller doesn't provide it, the library will have to buffer the contents of the input stream in order to calculate it since Amazon S3 explicitly requires that the content length be sent in the request headers before any of the data is sent.

  If versioning is enabled for the specified bucket, this operation will never overwrite an existing object with the same key, but instead will keep the existing object as an older version until that version is explicitly deleted (see `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. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

  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.

  Parameters:
    `putObjectRequest` - The request object containing all the parameters to upload a new object to Amazon S3.
  Returns:
    A `PutObjectResult` object containing the information returned by Amazon S3 for the new, created object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#putObject(String bucketName, String key, File file)}`

### putObject

    PutObjectResult putObject(String bucketName,
                              String key,
                              File file)
                              throws AmazonClientException,
                                     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.

  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.

  The file extension is used to try and automatically determine the correct content type to use for the object.

  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 `deleteVersion(String, String, String)`.

  If versioning is suspended or off, uploading an object to an existing key will overwrite the existing object because Amazon S3 stores the last write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

  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 you must have `Permission.Write` permission to the bucket to upload an object.

  Parameters:
    `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.
  Returns:
    A `PutObjectResult` object containing the information returned by Amazon S3 for the new, created object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3#putObject(PutObjectRequest putObjectRequest)}`

### putObject

    PutObjectResult putObject(String bucketName,
                              String key,
                              InputStream input,
                              ObjectMetadata metadata)
                              throws AmazonClientException,
                                     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 you don't receive an exception, then you can be confident that the entire object was stored.

  Callers should set the correct content type and content length in the metadata object before directly sending a stream. The library can't auto-determine content type for streams like it does for files, so if the caller doesn't set it, it won't be set in Amazon S3.

  Content length must be specified before data can be uploaded to Amazon S3. If the caller doesn't provide it, the library will have to buffer the contents of the input stream in order to calculate it since Amazon S3 explicitly requires that the content length be sent in the request headers before any of the data is sent.

  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 `deleteVersion(String, String, String)`.

  If versioning is suspended or off, uploading an object to an existing key will overwrite the existing object because Amazon S3 stores the last write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

  If you specify a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's region. For example, if you specify a region in Europe (EU) constraint for a bucket, all of that bucket's objects are stored in EU.

  The specified bucket must already exist and you must have `Permission.Write` permission to the bucket to upload an object.

  Parameters:
    `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 (ex: custom user metadata, hooks for specifying content type, etc.).
  Returns:
    A `PutObjectResult` object containing the information returned by Amazon S3 for the new, created object.
  Throws:
    `AmazonClientException` - 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.

### copyObject

    CopyObjectResult copyObject(String sourceBucketName,
                                String sourceKey,
                                String destinationBucketName,
                                String destinationKey)
                                throws AmazonClientException,
                                       AmazonServiceException

  Copies a source object to a new destination in Amazon S3.

  By default, all object metadata for the source object will be copied to the new destination object. 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`.

  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.

  Parameters:
    `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 may be the same name as the source bucket's.
    `destinationKey` - The key in the destination bucket under which the new object will be created.
  Returns:
    A `CopyObjectResult` object containing the information returned by Amazon S3 for the newly created object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#copyObject(CopyObjectRequest copyObjectRequest)}`

### copyObject

    CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
                                throws AmazonClientException,
                                       AmazonServiceException

  Copies a source object to a new destination in Amazon S3.

  By default, all object metadata for the source object will be 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` (ex: `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 uses, use the `AmazonS3Client.copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey)` method.

  Parameters:
    `copyObjectRequest` - The request object containing all the options for copying an Amazon S3 object.
  Returns:
    A `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 went to copy the object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey)}`

### deleteObject

    void deleteObject(String bucketName,
                      String key)
                      throws AmazonClientException,
                             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.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket containing the object to delete.
    `key` - The key of the object to delete.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#deleteObject(DeleteObjectRequest deleteObjectRequest)}`

### deleteObject

    void deleteObject(DeleteObjectRequest deleteObjectRequest)
                      throws AmazonClientException,
                             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.

  Parameters:
    `deleteObjectRequest` - The request object containing all options for deleting an S3 object.
  Throws:
    `AmazonClientException` - 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.
  See Also:
    `AmazonS3Client#deleteObject(String bucketName, String key)}`

### deleteVersion

    void deleteVersion(String bucketName,
                       String key,
                       String versionId)
                       throws AmazonClientException,
                              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.

  Since deleting an object version is permanent and irreversible, it is a privileged operation that only the owner of the bucket containing the version may perform.

  You can only delete a version of an object if you've enabled versioning for your bucket. See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Note: If you delete an object that does not exist, Amazon S3 will return a success (not an error message).

  Parameters:
    `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.
  Throws:
    `AmazonClientException` - 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.

### deleteVersion

    void deleteVersion(DeleteVersionRequest deleteVersionRequest)
                       throws AmazonClientException,
                              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.

  Since deleting an object version is permanent and irreversible, it is a privileged operation that only the owner of the bucket containing the version may perform.

  You can only delete a version of an object if you've enabled versioning for your bucket. See `setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)` for more information about enabling versioning for a bucket.

  Note: If you delete an object that does not exist, Amazon S3 will return a success (not an error message).

  Parameters:
    `deleteVersionRequest` - The request object containing all options for deleting a specific version of an S3 object.
  Throws:
    `AmazonClientException` - 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.

### getBucketLoggingConfiguration

    BucketLoggingConfiguration getBucketLoggingConfiguration(String bucketName)
                                                             throws AmazonClientException,
                                                                    AmazonServiceException

  Returns the logging configuration for the specified bucket. The bucket logging configuration object indicates whether server access logging is enabled or not for the specified bucket, and if so the destination bucket where server access logs are delivered, and the optional log file prefix.

  Parameters:
    `bucketName` - The name of the bucket whose bucket logging configuration is being retrieved.
  Returns:
    The bucket logging configuration for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketLoggingConfiguration

    void setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest setBucketLoggingConfigurationRequest)
                                       throws AmazonClientException,
                                              AmazonServiceException

  Sets the logging configuration for the specified bucket. The bucket logging configuration object controls whether server access logging is enabled or not for the specified bucket, and if so the destination bucket where server access logs are delivered (which may be the same bucket as the source bucket), and the optional log file prefix.

  In order to deliver server access logs, the destination bucket must have log delivery write permissions. You can use the `CannedAccessControlList.LogDeliveryWrite` ACL to quickly add the correct permissions to your destination bucket, or you can modify the bucket's existing ACL to grant the `GroupGrantee.LogDelivery` group grantee the `Permission.Write` permission.

  Changes to the logging status for a bucket are visible in the configuration API immediately, but they take time to actually affect the delivery of log files. For example, if you enable logging for a bucket, some requests made in the following hour might be logged, while others might not. Or, if you change the target bucket for logging from bucket A to bucket B, some logs for the next hour might continue to be delivered to bucket A, while others might be delivered to the new target bucket B. In all cases, the new settings will eventually take effect without any further action on your part.

  Parameters:
    `setBucketLoggingConfigurationRequest` - The request object containing all options for setting the bucket logging configuration.
  Throws:
    `AmazonClientException` - 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.

### getBucketVersioningConfiguration

    BucketVersioningConfiguration getBucketVersioningConfiguration(String bucketName)
                                                                   throws AmazonClientException,
                                                                          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 instance, when versioning is enabled, a PutObject operation creates a unique object version-id for the object being uploaded. 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 the DeleteVersion operation. It can never be overwritten. Additionally, PutObject 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.

  S3 is eventually consistent. It may take time for the versioning status of a bucket to be propagated throughout the system.

  Parameters:
    `bucketName` - The bucket whose versioning configuration will be retrieved.
  Returns:
    The bucket versioning configuration for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketVersioningConfiguration

    void setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
                                          throws AmazonClientException,
                                                 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 `Constants.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 instance, when versioning is enabled, a PutObject operation creates a unique object version-id for the object being uploaded. 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 the DeleteVersion operation. It can never be overwritten. Additionally, PutObject 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.

  S3 is eventually consistent. It may take time for the versioning status of a bucket to be propagated throughout the system.

  Parameters:
    `setBucketVersioningConfigurationRequest` - The request object containing all options for setting the bucket versioning configuration.
  Throws:
    `AmazonClientException` - 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.

### getBucketNotificationConfiguration

    BucketNotificationConfiguration getBucketNotificationConfiguration(String bucketName)
                                                                       throws AmazonClientException,
                                                                              AmazonServiceException

  Returns the notification configuration for the specified bucket.

  By default, new buckets have no notification configuration.

  The notification configuration of a bucket provides near realtime notifications of events the user is interested in, using SNS as the delivery service. Notification is turned on by enabling configuration on a bucket, specifying the events and the SNS topic. This configuration can only be turned on by the bucket owner. If a notification configuration already exists for the specified bucket, the new notification configuration will replace the existing notification configuration. To remove the notification configuration pass in an empty request. Currently, buckets may only have a single event and topic configuration.

  S3 is eventually consistent. It may take time for the notification status of a bucket to be propagated throughout the system.

  Parameters:
    `bucketName` - The bucket whose notification configuration will be retrieved.
  Returns:
    The bucket notification configuration for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketNotificationConfiguration

    void setBucketNotificationConfiguration(String bucketName,
                                            BucketNotificationConfiguration bucketNotificationConfiguration)
                                            throws AmazonClientException,
                                                   AmazonServiceException

  Sets the notification configuration for the specified bucket.

  By default, new buckets have no notification configuration set.

  The notification configuration of a bucket provides near realtime notifications of events the user is interested in, using SNS as the delivery service. Notification is turned on by enabling configuration on a bucket, specifying the events and the SNS topic. This configuration can only be turned on by the bucket owner. If a notification configuration already exists for the specified bucket, the new notification configuration will replace the existing notification configuration. To remove the notification configuration pass in an empty request. Currently, buckets may only have a single event and topic configuration.

  S3 is eventually consistent. It may take time for the notification status of a bucket to be propagated throughout the system.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose notification configuration is being set.
    `bucketNotificationConfiguration` - The request object containing all options for setting the bucket notification configuration.
  Throws:
    `AmazonClientException` - 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.

### getBucketPolicy

    BucketPolicy getBucketPolicy(String bucketName)
                                 throws AmazonClientException,
                                        AmazonServiceException

  Retrieves the policy for the specified bucket. Only the owner of the bucket can retrieve the policy. If no policy has been set for the bucket, then an empty result object with a null policy text field will be returned.

  Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources. Only one policy can be specified per-bucket.

  See the Amazon S3 developer guide for more information on forming bucket polices.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose policy is being retrieved.
  Returns:
    The Amazon S3 bucket policy for the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### setBucketPolicy

    void setBucketPolicy(String bucketName,
                         String policyText)
                         throws AmazonClientException,
                                AmazonServiceException

  Sets the policy associated with the specified bucket. Only the owner of the bucket can set a bucket policy. If a policy already exists for the specified bucket, the new policy will replace the existing policy.

  Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources. Only one policy may be specified per-bucket.

  See the Amazon S3 developer guide for more information on forming bucket polices.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose policy is being set.
    `policyText` - The policy to apply to the specified bucket.
  Throws:
    `AmazonClientException` - 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.

### deleteBucketPolicy

    void deleteBucketPolicy(String bucketName)
                            throws AmazonClientException,
                                   AmazonServiceException

  Deletes the policy associated with the specified bucket. Only the owner of the bucket can delete the bucket policy.

  Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources. Only one policy may be specified per-bucket.

  See the Amazon S3 developer guide for more information on forming bucket polices.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose policy is being deleted.
  Throws:
    `AmazonClientException` - 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.

### generatePresignedUrl

    URL generatePresignedUrl(String bucketName,
                             String key,
                             Date expiration)
                             throws AmazonClientException

  Returns a pre-signed GET URL to download the S3 object in the specified bucket under the specified key.

  Pre-signed URLs are useful for enabling direct third-party browser access to your private Amazon S3 data, without proxying the request, or exposing your AWS secret access key. The pre-signed request is encoded as a URL that any end-user's browser can retrieve.

  Pre-signed requests are limited by the specified expiration time. Once the expiration time passes, the pre-signed URL will stop working.

  Parameters:
    `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.
  Returns:
    A pre-signed URL which expires at the specified time, and can be used to allow anyone to download the specified object from S3, without exposing the owner's AWS secret access key.
  Throws:
    `AmazonClientException` - If there were any problems pre-signing the request for the specified S3 object.

### generatePresignedUrl

    URL generatePresignedUrl(String bucketName,
                             String key,
                             Date expiration,
                             HttpMethod method)
                             throws AmazonClientException

  Returns a pre-signed GET URL to download the S3 object in the specified bucket under the specified key.

  Pre-signed URLs are useful for enabling direct third-party browser access to your private Amazon S3 data, without proxying the request, or exposing your AWS secret access key. The pre-signed request is encoded as a URL that any end-user's browser can retrieve.

  Pre-signed requests are limited by the specified expiration time. Once the expiration time passes, the pre-signed URL will stop working.

  Parameters:
    `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 URL
  Returns:
    A pre-signed URL which expires at the specified time, and can be used to allow anyone to download the specified object from S3, without exposing the owner's AWS secret access key.
  Throws:
    `AmazonClientException` - If there were any problems pre-signing the request for the specified S3 object.

### generatePresignedUrl

    URL generatePresignedUrl(GeneratePresignedUrlRequest generatePresignedUrlRequest)
                             throws AmazonClientException

  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 sign it with the current AWS security credentials, then pass that pre-signed URL around for other people to access the resource without providing them access to an account's AWS security credentials.

  Pre-signed URLs can be 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 want to ship the owner's 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.

  Parameters:
    `generatePresignedUrlRequest` - The request object containing all the options for generating a pre-signed URL (bucket name, key, expiration date, etc).
  Returns:
    A pre-signed URL that can be used to access an Amazon S3 resource without requiring the user of the URL to know the account's AWS security credentials.
  Throws:
    `AmazonClientException` - If there were any problems pre-signing the request for the Amazon S3 resource.

Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010 Amazon Web Services, Inc. All Rights Reserved.