com.amazonaws.AmazonWebServiceClient
com.amazonaws.services.s3.AmazonS3Client
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class AmazonS3Client
Provides the client for accessing the Amazon S3 web service.
For more information about Amazon S3, please see http://aws.amazon.com/s3
| Constructor Summary | |
|---|---|
AmazonS3Client()
Constructs a new Amazon S3 client that will make anonymous requests to Amazon S3. |
|
AmazonS3Client(AWSCredentials awsCredentials)
Constructs a new Amazon S3 client using the specified AWS credentials to access Amazon S3. |
|
AmazonS3Client(AWSCredentials awsCredentials,
ClientConfiguration clientConfiguration)
Constructs a new Amazon S3 client using the specified AWS credentials and client configuration to access Amazon 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 |
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(String bucketName,
String key,
Date expiration)
Returns a pre-signed 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. |
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. |
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 maxKeys)
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 |
setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
Sets the versioning configuration for the specified bucket. |
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. |
| Methods inherited from class com.amazonaws.AmazonWebServiceClient |
|---|
setEndpoint |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface com.amazonaws.services.s3.AmazonS3 |
|---|
setEndpoint |
| Constructor Detail |
|---|
public AmazonS3Client()
Constructs a new Amazon S3 client that will make anonymous requests to Amazon S3.
Only a subset of the Amazon S3 API will work with anonymous (i.e. unsigned) requests, but this can prove useful in some situations. For example:
Permission.Read permission for the
GroupGrantee.AllUsers group, anonymous clients can call
listObjects(String) to see what objects are stored in a bucket.Permission.Read permission for the
GroupGrantee.AllUsers group, anonymous clients can call
getObject(String, String) and
getObjectMetadata(String, String) to pull object content and
metadata.Permission.Write permission for the
GroupGrantee.AllUsers group, anonymous clients can upload objects
to the bucket.
public AmazonS3Client(AWSCredentials awsCredentials)
Constructs a new Amazon S3 client using the specified AWS credentials to access Amazon S3.
awsCredentials - The AWS credentials to use when making requests to Amazon S3
with this client.
public AmazonS3Client(AWSCredentials awsCredentials,
ClientConfiguration clientConfiguration)
Constructs a new Amazon S3 client using the specified AWS credentials and client configuration to access Amazon S3.
awsCredentials - The AWS credentials to use when making requests to Amazon S3
with this client.clientConfiguration - The client configuration options controlling how this client
connects to Amazon S3 (ex: proxy settings, retry counts, etc).| Method Detail |
|---|
public VersionListing listNextBatchOfVersions(VersionListing previousVersionListing)
throws AmazonClientException,
AmazonServiceException
AmazonS3
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
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
listNextBatchOfVersions in interface AmazonS3previousVersionListing - The previous truncated VersionListing.
If a
non-truncated VersionListing is passed in, an empty
VersionListing will be returned without ever contacting
Amazon S3.
VersionListing results, beginning immediately
after the last result in the specified previous VersionListing.
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(String, String),
listVersions(ListVersionsRequest)
public VersionListing listVersions(String bucketName,
String prefix)
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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
AmazonS3.listNextBatchOfVersions(VersionListing) as an easy way
to get the next page of results.
See
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
listVersions in interface AmazonS3bucketName - 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.
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.
public VersionListing listVersions(String bucketName,
String prefix,
String keyMarker,
String versionIdMarker,
String delimiter,
Integer maxKeys)
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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
AmazonS3.listNextBatchOfVersions(VersionListing) as an easy way
to get the next page of results.
The keyMarker and versionIdMarker parameters allow
callers to specify where to start the version listing.
The delimiter parameter allows groups of keys that share a
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, much like how a file system organizes
files into directories. These common prefixes can be retrieved
by calling the VersionListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
listVersions with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, a VersionListing is returned that contains:
To see deeper into the virtual hierarchy, make
another call to listVersions setting the prefix parameter to any
interesting common prefix to list the individual versions under that
prefix.
See
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
listVersions in interface AmazonS3bucketName - 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
AmazonS3.listNextBatchOfVersions(VersionListing)
versionIdMarker - Optional parameter indicating where in the sorted list of all
versions in the specified bucket to begin returning results.
Results are always ordered first lexicographically (i.e.
alphabetically) and then from most recent version to least
recent version. A keyMarker must be specified when specifying
a versionIdMarker. Results begin immediately after the version
with the specified key and version ID.
This enables pagination: to get the next page of results use
the next key marker and next version ID marker (from
VersionListing.getNextKeyMarker() and
VersionListing.getNextVersionIdMarker()) as the
markers for the next request to list versions. Or use the
convenience method
AmazonS3.listNextBatchOfVersions(VersionListing)
delimiter - Optional parameter that causes keys that contain the same
string between the prefix and the first occurrence of the
delimiter to be rolled up into a single result element in the
VersionListing.getCommonPrefixes() list. These
rolled-up keys are not returned elsewhere in the response. The
most commonly used delimiter is "/", which simulates a
hierarchical organization similar to a file system directory
structure.maxKeys - 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.
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.
public VersionListing listVersions(ListVersionsRequest listVersionsRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3The 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
AmazonS3.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:
If you call listVersions with prefix="foo/" and delimiter="/" on this bucket, you will get an S3VersionListing back that contains:
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
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
listVersions in interface AmazonS3listVersionsRequest - The request object containing all options for listing the
versions in a specified bucket.
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.
public ObjectListing listObjects(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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
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.
listObjects in interface AmazonS3bucketName - The name of the Amazon S3 bucket to list.
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.AmazonS3Client#listObjects(String bucketName, String prefix)},
AmazonS3Client#listObjects(ListObjectsRequest listObjectsRequest)}
public ObjectListing listObjects(String bucketName,
String prefix)
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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
listNextBatchOfObjects(ObjectListing) method as
an easy way to get the next page of object listings.
For example, consider a bucket that contains the following keys:
listObjects with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an ObjectListing is returned that contains one key
("foo/boo") and one entry in the common prefixes list ("foo/bar/").
To see deeper into the virtual hierarchy, make another
call to listObjects setting the prefix parameter to any interesting
common prefix to list the individual keys under that prefix.
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.
listObjects in interface AmazonS3bucketName - 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.
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.AmazonS3Client#listObjects(String bucketName)},
AmazonS3Client#listObjects(ListObjectsRequest listObjectsRequest)}
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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
listNextBatchOfObjects(ObjectListing) method as
an easy way to get the next page of object listings.
Calling ListObjectsRequest.setDelimiter(String)
sets the delimiter, allowing groups of keys that share the
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, similar to how a file system organizes files
into directories. These common prefixes can be retrieved
through the ObjectListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
listObjects with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an ObjectListing is returned that contains one key
("foo/boo") and one entry in the common prefixes list ("foo/bar/").
To see deeper into the virtual hierarchy, make another
call to listObjects setting the prefix parameter to any interesting
common prefix to list the individual keys under that prefix.
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.
listObjects in interface AmazonS3listObjectsRequest - The request object containing all options for listing the
objects in a specified bucket.
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.AmazonS3Client#listObjects(String bucketName)},
AmazonS3Client#listObjects(String bucketName, String prefix)}
public ObjectListing listNextBatchOfObjects(ObjectListing previousObjectListing)
throws AmazonClientException,
AmazonServiceException
AmazonS3Provides 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.
listNextBatchOfObjects in interface AmazonS3previousObjectListing - The previous truncated ObjectListing.
If a
non-truncated ObjectListing is passed in, an empty
ObjectListing will be returned without ever contacting
Amazon S3.
ObjectListing results, beginning immediately
after the last result in the specified previous ObjectListing.
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(String),
listObjects(String, String),
listObjects(ListObjectsRequest)
public Owner getS3AccountOwner()
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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.
getS3AccountOwner in interface AmazonS3AmazonClientException - 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.
public List<Bucket> listBuckets()
throws AmazonClientException,
AmazonServiceException
AmazonS3Returns 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.
listBuckets in interface AmazonS3AmazonClientException - 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.
public String getBucketLocation(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3To 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.
getBucketLocation in interface AmazonS3bucketName - The name of the Amazon S3 bucket to look up. This must be a
bucket that you own.
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.Region
public Bucket createBucket(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3Region.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:
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.
createBucket in interface AmazonS3bucketName - The name of the bucket to create.
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.
public Bucket createBucket(String bucketName,
Region region)
throws AmazonClientException,
AmazonServiceException
AmazonS3Every 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:
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.
createBucket in interface AmazonS3bucketName - The name of the bucket to create. Bucket names are globally
unique, soregion - The Amazon S3 region in which to create the new bucket.
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.Region
public Bucket createBucket(String bucketName,
String region)
throws AmazonClientException,
AmazonServiceException
AmazonS3AmazonS3.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:
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.
createBucket in interface AmazonS3bucketName - The name of the bucket to create. Bucket names are globally
unique, soregion - The Amazon S3 region in which to create the new bucket.
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.Region
public Bucket createBucket(CreateBucketRequest createBucketRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Region.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:
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.
createBucket in interface AmazonS3createBucketRequest - The request object containing all options for creating an S3
bucket.
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.
public AccessControlList getObjectAcl(String bucketName,
String key)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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.
getObjectAcl in interface AmazonS3bucketName - 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.
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.
public AccessControlList getObjectAcl(String bucketName,
String key,
String versionId)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
getObjectAcl in interface AmazonS3bucketName - 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.
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.
public void setObjectAcl(String bucketName,
String key,
AccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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 (
getObjectAcl(String, String)), modify it as
necessary, and then use this method to upload the new ACL.
setObjectAcl in interface AmazonS3bucketName - 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.
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.
public void setObjectAcl(String bucketName,
String key,
CannedAccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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.
setObjectAcl in interface AmazonS3bucketName - 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.
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.
public void setObjectAcl(String bucketName,
String key,
String versionId,
AccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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 (
getObjectAcl(String, String)), modify it as
necessary, and then use this method to upload the new ACL.
See
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
setObjectAcl in interface AmazonS3bucketName - 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.
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.
public void setObjectAcl(String bucketName,
String key,
String versionId,
CannedAccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
setObjectAcl in interface AmazonS3bucketName - 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.
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.
public AccessControlList getBucketAcl(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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.
getBucketAcl in interface AmazonS3bucketName - The name of the bucket whose ACL is being retrieved.
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.
public void setBucketAcl(String bucketName,
AccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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 (
getBucketAcl(String)), modify it as necessary, and
then use this method to upload the new ACL.
setBucketAcl in interface AmazonS3bucketName - The name of the bucket whose ACL is being set.acl - The new AccessControlList for the specified bucket.
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.
public void setBucketAcl(String bucketName,
CannedAccessControlList acl)
throws AmazonClientException,
AmazonServiceException
AmazonS3Each 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.
setBucketAcl in interface AmazonS3bucketName - The name of the bucket whose ACL is being set.acl - The pre-configured CannedAccessControlList to set for the
specified bucket.
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.
public ObjectMetadata getObjectMetadata(String bucketName,
String key)
throws AmazonClientException,
AmazonServiceException
AmazonS3Gets 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.
getObjectMetadata in interface AmazonS3bucketName - 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.
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.AmazonS3#getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)}
public ObjectMetadata getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Gets 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
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
for more information about enabling versioning for a bucket.
getObjectMetadata in interface AmazonS3getObjectMetadataRequest - The request object specifying the bucket, key and optional
version ID of the object whose metadata is being retrieved.
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.AmazonS3#getObjectMetadata(String bucketName, String key)}
public S3Object getObject(String bucketName,
String key)
throws AmazonClientException,
AmazonServiceException
AmazonS3Gets 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:
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 AmazonS3.getObject(GetObjectRequest).
getObject in interface AmazonS3bucketName - The name of the bucket containing the desired object.key - The key under which the desired object is stored.
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.AmazonS3#getObject(GetObjectRequest getObjectRequest)},
AmazonS3#getObject(GetObjectRequest getObjectRequest, File destinationFile)}
public boolean doesBucketExist(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3
doesBucketExist in interface AmazonS3bucketName - The name of the bucket to check.
true if the specified bucket exists in
Amazon S3; a value
of false if there is no bucket in Amazon S3 with that name.
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.
public void changeObjectStorageClass(String bucketName,
String key,
StorageClass newStorageClass)
throws AmazonClientException,
AmazonServiceException
AmazonS3Note 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.
changeObjectStorageClass in interface AmazonS3bucketName - 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.
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.
public S3Object getObject(GetObjectRequest getObjectRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3
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:
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 AmazonS3.getObject(String bucketName, String key) method.
getObject in interface AmazonS3getObjectRequest - The request object containing all the options on how to
download the object.
null if constraints were specified but not met.
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.AmazonS3#getObject(String bucketName, String key)},
AmazonS3#getObject(GetObjectRequest getObjectRequest, File destinationFile)}
public ObjectMetadata getObject(GetObjectRequest getObjectRequest,
File destinationFile)
throws AmazonClientException,
AmazonServiceException
AmazonS3
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
AmazonS3.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.
getObject in interface AmazonS3getObjectRequest - 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.
null if constraints were specified but not met.
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.AmazonS3#getObject(String bucketName, String key)},
AmazonS3#getObject(GetObjectRequest getObjectRequest)}
public void deleteBucket(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3Only the owner of a bucket can delete it, regardless of the bucket's access control policy.
deleteBucket in interface AmazonS3bucketName - The name of the bucket to delete.
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.
public void deleteBucket(DeleteBucketRequest deleteBucketRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Only the owner of a bucket can delete it, regardless of the bucket's access control policy.
deleteBucket in interface AmazonS3deleteBucketRequest - The request object containing all options for delete an S3
bucket.
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.
public PutObjectResult putObject(String bucketName,
String key,
File file)
throws AmazonClientException,
AmazonServiceException
AmazonS3Uploads 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
AmazonS3.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.
putObject in interface AmazonS3bucketName - The name of an existing bucket, to which you have
Permission.Write permission.key - The key under which to store the specified file.file - The file containing the data to be uploaded to Amazon S3.
PutObjectResult object containing the information
returned by Amazon S3 for the new, created object.
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.AmazonS3#putObject(PutObjectRequest putObjectRequest)}
public PutObjectResult putObject(String bucketName,
String key,
InputStream input,
ObjectMetadata metadata)
throws AmazonClientException,
AmazonServiceException
AmazonS3Amazon 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
AmazonS3.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.
putObject in interface AmazonS3bucketName - 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.).
PutObjectResult object containing the information
returned by Amazon S3 for the new, created object.
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.
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3
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:
When uploading directly from an input stream:
If versioning is enabled for the specified bucket, this operation will
never overwrite an existing object with the same key, but instead will keep
the existing object as an older version until that version is
explicitly deleted (see
AmazonS3.deleteVersion(String, String, String).
If versioning is not enabled,this operation will overwrite an existing object with the same key; Amazon S3 will store the last write request. 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.
putObject in interface AmazonS3putObjectRequest - The request object containing all the parameters to upload a
new object to Amazon S3.
PutObjectResult object containing the information
returned by Amazon S3 for the new, created object.
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.AmazonS3#putObject(String bucketName, String key, File file)}
public CopyObjectResult copyObject(String sourceBucketName,
String sourceKey,
String destinationBucketName,
String destinationKey)
throws AmazonClientException,
AmazonServiceException
AmazonS3Copies 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
copyObject(CopyObjectRequest) method, including
conditional constraints for copying objects, setting ACLs, overwriting
object metadata, etc.
copyObject in interface AmazonS3sourceBucketName - 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.
CopyObjectResult object containing the information
returned by Amazon S3 for the newly created object.
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.AmazonS3Client#copyObject(CopyObjectRequest copyObjectRequest)}
public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Copies 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
copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey)
method.
copyObject in interface AmazonS3copyObjectRequest - The request object containing all the options for copying an
Amazon S3 object.
CopyObjectResult object containing the information
returned by Amazon S3 about the newly created object, or null if
constraints were specified that weren't met when Amazon S3 went
to copy the object.
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.AmazonS3Client#copyObject(String sourceBucketName, String sourceKey, String destinationBucketName, String destinationKey)}
public void deleteObject(String bucketName,
String key)
throws AmazonClientException,
AmazonServiceException
AmazonS3Deletes 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.
deleteObject in interface AmazonS3bucketName - The name of the Amazon S3 bucket containing the object to
delete.key - The key of the object to delete.
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.AmazonS3Client#deleteObject(DeleteObjectRequest deleteObjectRequest)}
public void deleteObject(DeleteObjectRequest deleteObjectRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Deletes 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.
deleteObject in interface AmazonS3deleteObjectRequest - The request object containing all options for deleting an S3
object.
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.AmazonS3Client#deleteObject(String bucketName, String key)}
public void deleteVersion(String bucketName,
String key,
String versionId)
throws AmazonClientException,
AmazonServiceException
AmazonS3Since 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
AmazonS3.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).
deleteVersion in interface AmazonS3bucketName - 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.
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.
public void deleteVersion(DeleteVersionRequest deleteVersionRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3Since 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
AmazonS3.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).
deleteVersion in interface AmazonS3deleteVersionRequest - The request object containing all options for deleting a
specific version of an S3 object.
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.
public void setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3A 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.
setBucketVersioningConfiguration in interface AmazonS3setBucketVersioningConfigurationRequest - The request object containing all options for setting the
bucket versioning configuration.
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.
public BucketVersioningConfiguration getBucketVersioningConfiguration(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3A 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.
getBucketVersioningConfiguration in interface AmazonS3bucketName - The bucket whose versioning configuration will be retrieved.
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.
public BucketLoggingConfiguration getBucketLoggingConfiguration(String bucketName)
throws AmazonClientException,
AmazonServiceException
AmazonS3
getBucketLoggingConfiguration in interface AmazonS3bucketName - The name of the bucket whose bucket logging configuration is
being retrieved.
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.
public void setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest setBucketLoggingConfigurationRequest)
throws AmazonClientException,
AmazonServiceException
AmazonS3
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.
setBucketLoggingConfiguration in interface AmazonS3setBucketLoggingConfigurationRequest - The request object containing all options for setting the
bucket logging configuration.
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.
public URL generatePresignedUrl(String bucketName,
String key,
Date expiration)
throws AmazonClientException
AmazonS3Pre-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.
generatePresignedUrl in interface AmazonS3bucketName - 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.
AmazonClientException - If there were any problems pre-signing the request for the
specified S3 object.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||