org.jclouds.s3
Interface S3Client

All Known Subinterfaces:

AWSS3Client

public interface S3Client

Provides access to S3 via their REST API.

All commands return a Future of the result from S3. Any exceptions incurred during processing will be wrapped in an ExecutionException as documented in Future.get().

Author:

Adrian Cole, James Murty

See Also:

Method Summary

boolean	bucketExists(String bucketName) Issues a HEAD command to determine if the bucket exists or not.
ObjectMetadata	copyObject(String sourceBucket, String sourceObject, String destinationBucket, String destinationObject, CopyObjectOptions... options) Copies one object to another bucket, retaining UserMetadata from the source.
boolean	deleteBucketIfEmpty(String bucketName) Deletes the bucket, if it is empty.
void	deleteObject(String bucketName, String key) Removes the object and metadata associated with the key.
void	disableBucketLogging(String bucketName) Disables logging for a bucket.
void	enableBucketLogging(String bucketName, BucketLogging logging) Enables logging for a bucket.
AccessControlList	getBucketACL(String bucketName) A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.
String	getBucketLocation(String bucketName) A GET location request operation using a bucket URI lists the location constraint of the bucket.
BucketLogging	getBucketLogging(String bucketName) Inspects the logging status for a bucket.
Payer	getBucketPayer(String bucketName) A GET request operation on a requestPayment resource returns the request payment configuration of a bucket.
S3Object	getObject(String bucketName, String key, GetOptions... options) Retrieves the S3Object associated with the Key or KeyNotFoundException if not available; To use GET, you must have READ access to the object.
AccessControlList	getObjectACL(String bucketName, String key) A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.
ObjectMetadata	headObject(String bucketName, String key) Retrieves the metadata of the object associated with the key or org.jclouds.s3.domain.internal.BucketListObjectMetadata#NOT_FOUND if not available.
ListBucketResponse	listBucket(String bucketName, ListBucketOptions... options) Retrieve a S3Bucket listing.
Set<BucketMetadata>	listOwnedBuckets() Returns a list of all of the buckets owned by the authenticated sender of the request.
S3Object	newS3Object() Creates a default implementation of S3Object
boolean	objectExists(String bucketName, String key)
boolean	putBucketACL(String bucketName, AccessControlList acl) Update a bucket's Access Control List settings.
boolean	putBucketInRegion(String region, String bucketName, PutBucketOptions... options) Create and name your own bucket in which to store your objects.
String	putObject(String bucketName, S3Object object, PutObjectOptions... options) Store data by creating or overwriting an object.
boolean	putObjectACL(String bucketName, String key, AccessControlList acl) Update an object's Access Control List settings.
void	setBucketPayer(String bucketName, Payer payer) The PUT request operation with a requestPayment URI configures an existing bucket to be Requester Pays or not.

Method Detail

newS3Object

@Provides
S3Object newS3Object()

Creates a default implementation of S3Object

getObject

S3Object getObject(String bucketName,
                   String key,
                   GetOptions... options)

Retrieves the S3Object associated with the Key or KeyNotFoundException if not available;

To use GET, you must have READ access to the object. If READ access is granted to the anonymous user, you can request the object without an authorization header.

This command allows you to specify GetObjectOptions to control delivery of content.

Note

If you specify any of the below options, you will receive partial content:

• GetObjectOptions#range
• GetObjectOptions#startAt
• GetObjectOptions#tail

Timeout

The maximum size of an object in S3 is 5GB. We've set the timeout according to a rate of 512kb/s for the maximum size. If you wish a shorter timeout, please use the S3AsyncClient interface}.

Parameters:

bucketName - namespace of the object you are retrieving

key - unique key in the s3Bucket identifying the object

Returns:

Future reference to a fully populated S3Object including data stored in S3 or S3Object#NOT_FOUND if not present.

Throws:

HttpResponseException - if the conditions requested set were not satisfied by the object on the server.

See Also:

#getObject(String, String), GetObjectOptions

headObject

ObjectMetadata headObject(String bucketName,
                          String key)

Retrieves the metadata of the object associated with the key or org.jclouds.s3.domain.internal.BucketListObjectMetadata#NOT_FOUND if not available.

The HEAD operation is used to retrieve information about a specific object or object size, without actually fetching the object itself. This is useful if you're only interested in the object metadata, and don't want to waste bandwidth on the object data.

Parameters:

bucketName - namespace of the metadata you are retrieving

key - unique key in the s3Bucket identifying the object

Returns:

metadata associated with the key or org.jclouds.s3.domain.internal.BucketListObjectMetadata#NOT_FOUND if not present;

See Also:

#getObject(String, String),

objectExists

boolean objectExists(String bucketName,
                     String key)

deleteObject

void deleteObject(String bucketName,
                  String key)

Removes the object and metadata associated with the key.

The DELETE request operation removes the specified object from Amazon S3. Once deleted, there is no method to restore or undelete an object.

Parameters:

bucketName - namespace of the object you are deleting

key - unique key in the s3Bucket identifying the object

Throws:

HttpResponseException - if the bucket is not available

See Also:

putObject

String putObject(String bucketName,
                 S3Object object,
                 PutObjectOptions... options)

Store data by creating or overwriting an object.

This method will store the object with the default private This returns a byte[] of the eTag hash of what Amazon S3 received

Timeout

The maximum size of an object in S3 is 5GB. We've set the timeout according to a rate of 128kb/s for the maximum size. If you wish a shorter timeout, please use the S3AsyncClient interface}.

Parameters:

bucketName - namespace of the object you are storing

object - contains the data and metadata to create or overwrite

options - options for creating the object

Returns:

ETag of the content uploaded

Throws:

HttpResponseException - if the conditions requested set are not satisfied by the object on the server.

See Also:

CannedAccessPolicy.PRIVATE,

putBucketInRegion

boolean putBucketInRegion(@Nullable
                          String region,
                          String bucketName,
                          PutBucketOptions... options)

Create and name your own bucket in which to store your objects.

you can use PutBucketOptions to create the bucket in EU.

The PUT request operation with a bucket URI creates a new bucket. Depending on your latency and legal requirements, you can specify a location constraint that will affect where your data physically resides. You can currently specify a Europe (EU) location constraint via PutBucketOptions.

Parameters:

options - for creating your bucket

Returns:

true, if the bucket was created or false, if the container was already present

See Also:

PutBucketOptions,

deleteBucketIfEmpty

boolean deleteBucketIfEmpty(String bucketName)

Deletes the bucket, if it is empty.

The DELETE request operation deletes the bucket named in the URI. All objects 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 - what to delete

Returns:

false, if the bucket was not empty and therefore not deleted

See Also:

org.jclouds.s3.commands.DeleteBucket,

bucketExists

boolean bucketExists(String bucketName)

Issues a HEAD command to determine if the bucket exists or not.

listBucket

ListBucketResponse listBucket(String bucketName,
                              ListBucketOptions... options)

Retrieve a S3Bucket listing. A GET request operation using a bucket URI lists information about the objects in the bucket. You can use ListBucketOptions to control the amount of S3Objects to return.

To list the keys of a bucket, you must have READ access to the bucket.

Parameters:

bucketName - namespace of the objects you wish to list

Returns:

Future reference to a fully populated S3Bucket including metadata of the S3Objects it contains or BoundedList#NOT_FOUND if not present.

See Also:

ListBucketOptions,

listOwnedBuckets

Set<BucketMetadata> listOwnedBuckets()

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

Returns:

list of all of the buckets owned by the authenticated sender of the request.

See Also:

copyObject

ObjectMetadata copyObject(String sourceBucket,
                          String sourceObject,
                          String destinationBucket,
                          String destinationObject,
                          CopyObjectOptions... options)

Copies one object to another bucket, retaining UserMetadata from the source. The destination will have a private acl. The copy operation creates a copy of an object that is already stored in Amazon S3.

When copying an object, you can preserve all metadata (default) or specify new metadata. However, the ACL is not preserved and is set to private for the user making the request. To override the default ACL setting, specify a new ACL when generating a copy request.

Returns:

metadata populated with lastModified and eTag of the new object

Throws:

HttpResponseException - if the conditions requested set are not satisfied by the object on the server.

See Also:

org.jclouds.s3.commands.CopyObject, , CopyObjectOptions, CannedAccessPolicy

getBucketACL

AccessControlList getBucketACL(String bucketName)

A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.

To list a bucket's ACL, you must have READ_ACP access to the item.

Returns:

access permissions of the bucket

See Also:

putBucketACL

boolean putBucketACL(String bucketName,
                     AccessControlList acl)

Update a bucket's Access Control List settings.

A PUT request operation directed at a bucket URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

Parameters:

bucketName - the bucket whose Access Control List settings will be updated.

acl - the ACL to apply to the bucket. This acl object mustAccessControlList.getOwner().

Returns:

true if the bucket's Access Control List was updated successfully.

See Also:

getObjectACL

AccessControlList getObjectACL(String bucketName,
                               String key)

A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.

To list a object's ACL, you must have READ_ACP access to the item.

Returns:

access permissions of the object

See Also:

putObjectACL

boolean putObjectACL(String bucketName,
                     String key,
                     AccessControlList acl)

Update an object's Access Control List settings.

A PUT request operation directed at an object URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

Parameters:

bucket - the bucket containing the object to be updated

objectKey - the key of the object whose Access Control List settings will be updated.

acl - the ACL to apply to the object. This acl object mustAccessControlList.getOwner().

Returns:

true if the object's Access Control List was updated successfully.

See Also:

getBucketLocation

String getBucketLocation(String bucketName)

A GET location request operation using a bucket URI lists the location constraint of the bucket.

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

Parameters:

bucket - the bucket you wish to know where exists

Returns:

location of the bucket

See Also:

getBucketPayer

Payer getBucketPayer(String bucketName)

A GET request operation on a requestPayment resource returns the request payment configuration of a bucket.

Only the bucket owner has permissions to get this value.

Parameters:

bucketName - the bucket you wish to know the payer status

Returns:

Payer.REQUESTER for a Requester Pays bucket, and Payer.BUCKET_OWNER, for a normal bucket.

See Also:

setBucketPayer

void setBucketPayer(String bucketName,
                    Payer payer)

The PUT request operation with a requestPayment URI configures an existing bucket to be Requester Pays or not. To make a bucket a Requester Pays bucket, make the Payer value Requester. Otherwise, make the value BucketOwner.

Only a bucket owner is allowed to configure a bucket. As a result any requests for this resource should be signed with the bucket owner's credentials. Anonymous requests are never allowed to create Requester Pays buckets.

Parameters:

bucketName - the bucket you wish to know the payer status

payer - Payer.REQUESTER for a Requester Pays bucket, and Payer.BUCKET_OWNER, for a normal bucket.

See Also:

getBucketLogging

BucketLogging getBucketLogging(String bucketName)

Inspects the logging status for a bucket.

Parameters:

bucketName - the bucket you wish to know the logging status

Returns:

bucketLogging configuration or null, if not configured

See Also:

enableBucketLogging

void enableBucketLogging(String bucketName,
                         BucketLogging logging)

Enables logging for a bucket.

Parameters:

bucketName - the bucket you wish to enable logging for

logging - configuration including destination, prefix, and access rules

See Also:

disableBucketLogging

void disableBucketLogging(String bucketName)

Disables logging for a bucket.

Parameters:

bucketName - the bucket you wish to disable logging for

See Also: