S3Client (jclouds 1.4.1 API)

Methods
Modifier and Type	Method and Description
`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.

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

Methods
Modifier and Type Method and Description

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:

Interface S3Client

Method Summary

Method Detail

newS3Object

getObject

Note

Timeout

headObject

objectExists

deleteObject

putObject

Timeout

putBucketInRegion

deleteBucketIfEmpty

bucketExists

listBucket

listOwnedBuckets

copyObject

getBucketACL

putBucketACL

getObjectACL

putObjectACL

getBucketLocation

getBucketPayer

setBucketPayer

getBucketLogging

enableBucketLogging

disableBucketLogging