org.jclouds.aws.s3
Interface AWSS3Client

All Superinterfaces:

S3Client

public interface AWSS3Client
extends S3Client

Provides access to amazon-specific S3 features

Author:

Adrian Cole

See Also:

AWSS3AsyncClient

Method Summary

void	abortMultipartUpload(String bucketName, String key, String uploadId) This operation aborts a multipart upload.
String	completeMultipartUpload(String bucketName, String key, String uploadId, Map<Integer,String> parts) This operation completes a multipart upload by assembling previously uploaded parts.
String	initiateMultipartUpload(String bucketName, ObjectMetadata objectMetadata, PutObjectOptions... options) This operation initiates a multipart upload and returns an upload ID.
String	uploadPart(String bucketName, String key, int partNumber, String uploadId, Payload part) This operation uploads a part in a multipart upload.

Methods inherited from interface org.jclouds.s3.S3Client

bucketExists, copyObject, deleteBucketIfEmpty, deleteObject, disableBucketLogging, enableBucketLogging, getBucketACL, getBucketLocation, getBucketLogging, getBucketPayer, getObject, getObjectACL, headObject, listBucket, listOwnedBuckets, newS3Object, objectExists, putBucketACL, putBucketInRegion, putObject, putObjectACL, setBucketPayer

Method Detail

initiateMultipartUpload

String initiateMultipartUpload(String bucketName,
                               ObjectMetadata objectMetadata,
                               PutObjectOptions... options)

This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests (see Upload Part). You also include this upload ID in the final request to either complete or abort the multipart upload request.

Note

If you create an object using the multipart upload APIs, currently you cannot copy the object between regions.

Parameters:

bucketName - namespace of the object you are to upload

objectMetadata - metadata around the object you wish to upload

options - controls optional parameters such as canned ACL

Returns:

ID for the initiated multipart upload.

abortMultipartUpload

void abortMultipartUpload(String bucketName,
                          String key,
                          String uploadId)

This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.

Parameters:

bucketName - namespace of the object you are deleting

key - unique key in the s3Bucket identifying the object

uploadId - id of the multipart upload in progress.

uploadPart

String uploadPart(String bucketName,
                  String key,
                  int partNumber,
                  String uploadId,
                  Payload part)

This operation uploads a part in a multipart upload. You must initiate a multipart upload (see Initiate Multipart Upload) before you can upload any part. In response to your initiate request. Amazon S3 returns an upload ID, a unique identifier, that you must include in your upload part request.

Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being created. If you upload a new part using the same part number that was used with a previous part, the previously uploaded part is overwritten. Each part must be at least 5 MB in size, except the last part. There is no size limit on the last part of your multipart upload.

To ensure that data is not corrupted when traversing the network, specify the Content-MD5 header in the upload part request. Amazon S3 checks the part data against the provided MD5 value. If they do not match, Amazon S3 returns an error.

Parameters:

bucketName - namespace of the object you are storing

key - unique key in the s3Bucket identifying the object

partNumber - which part is this.

uploadId - id of the multipart upload in progress.

part - contains the data to create or overwrite

Returns:

ETag of the content uploaded

See Also:

completeMultipartUpload

String completeMultipartUpload(String bucketName,
                               String key,
                               String uploadId,
                               Map<Integer,String> parts)

This operation completes a multipart upload by assembling previously uploaded parts.

You first initiate the multipart upload and then upload all parts using the Upload Parts operation (see Upload Part). After successfully uploading all relevant parts of an upload, you call this operation to complete the upload. Upon receiving this request, Amazon S3 concatenates all the parts in ascending order by part number to create a new object. In the Complete Multipart Upload request, you must provide the parts list. For each part in the list, you must provide the part number and the ETag header value, returned after that part was uploaded.

Processing of a Complete Multipart Upload request could take several minutes to complete. After Amazon S3 begins processing the request, it sends an HTTP response header that specifies a 200 OK response. While processing is in progress, Amazon S3 periodically sends whitespace characters to keep the connection from timing out. Because a request could fail after the initial 200 OK response has been sent, it is important that you check the response body to determine whether the request succeeded.

Note that if Complete Multipart Upload fails, applications should be prepared to retry the failed requests.

Parameters:

bucketName - namespace of the object you are deleting

key - unique key in the s3Bucket identifying the object

uploadId - id of the multipart upload in progress.

parts - a map of part id to eTag from the uploadPart(java.lang.String, java.lang.String, int, java.lang.String, org.jclouds.io.Payload) command.

Returns:

ETag of the content uploaded