com.ibm.cloud.objectstorage.services.s3

Class UploadObjectObserver

java.lang.Object

com.ibm.cloud.objectstorage.services.s3.UploadObjectObserver

public class UploadObjectObserver
extends Object

An observer that gets notified of ciphertext file creation for the purpose of pipelined parallel multi-part uploads of encrypted data to S3. This observer is responsible for uploading the files to S3 via multi-part upload, including the multi-part upload initiation, individual part uploads, and multi-part upload completion.

This observer is designed for extension so that custom behavior can be provided. A customer observer can be configured via UploadObjectRequest.withUploadObjectObserver(UploadObjectObserver).

See Also:

UploadObjectRequest

Constructor Summary

Constructors

Constructor and Description
UploadObjectObserver()

Method Summary

Modifier and Type	Method and Description
protected <X extends AmazonWebServiceRequest> X	appendUserAgent(X request, String userAgent) Appends the given user agent to the given request.
protected AmazonS3	getAmazonS3() Returns the AmazonS3 instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)
protected ExecutorService	getExecutorService() Returns the ExecutorService instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)
List<Future<UploadPartResult>>	getFutures()
protected UploadObjectRequest	getRequest() Returns the request initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)
protected S3DirectSpi	getS3DirectSpi() Returns the S3DirectSpi instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)
protected String	getUploadId() Returns the upload id after the multi-part upload has been initiated via UploadObjectObserver.onUploadInitiation(UploadObjectRequest)
UploadObjectObserver	init(UploadObjectRequest req, S3DirectSpi s3direct, AmazonS3 s3, ExecutorService es) Used to initialized this observer.
protected InitiateMultipartUploadRequest	newInitiateMultipartUploadRequest(UploadObjectRequest req)
protected UploadPartRequest	newUploadPartRequest(PartCreationEvent event, File part) Creates and returns an upload-part request corresponding to a ciphertext file upon a part-creation event.
void	onAbort() Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) when failed to upload any part.
CompleteMultipartUploadResult	onCompletion(List<PartETag> partETags) Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) when all parts have been successfully uploaded to S3.
void	onPartCreate(PartCreationEvent event) Notified from MultiFileOutputStream.fos() when a part ready for upload has been successfully created on disk.
String	onUploadInitiation(UploadObjectRequest req) Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) to initiate a multi-part upload.
protected UploadPartResult	uploadPart(UploadPartRequest reqUploadPart) Uploads the ciphertext via the non-encrypting s3 client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UploadObjectObserver

public UploadObjectObserver()

Method Detail

init

public UploadObjectObserver init(UploadObjectRequest req,
                                 S3DirectSpi s3direct,
                                 AmazonS3 s3,
                                 ExecutorService es)

Used to initialized this observer. This method is an SPI (service provider interface) that is called from AmazonS3EncryptionClient.

Implementation of this method should never block.

Parameters:

req - the upload object request

s3direct - used to perform non-encrypting s3 operation via the current instance of s3 (encryption) client

s3 - the current instance of s3 (encryption) client

es - the executor service to be used for concurrent uploads

Returns:

this object

newInitiateMultipartUploadRequest

protected InitiateMultipartUploadRequest newInitiateMultipartUploadRequest(UploadObjectRequest req)

onUploadInitiation

public String onUploadInitiation(UploadObjectRequest req)

Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) to initiate a multi-part upload.

Parameters:

req - the upload object request

Returns:

the initiated multi-part uploadId

onPartCreate

public void onPartCreate(PartCreationEvent event)

Notified from MultiFileOutputStream.fos() when a part ready for upload has been successfully created on disk. By default, this method performs the following:

1. calls UploadObjectObserver.newUploadPartRequest(PartCreationEvent, File) to create an upload-part request for the newly created ciphertext file
2. call UploadObjectObserver.appendUserAgent(AmazonWebServiceRequest, String) to append the necessary user agent string to the request
3. and finally submit a concurrent task, which calls the method UploadObjectObserver.uploadPart(UploadPartRequest), to be performed

To enable parallel uploads, implementation of this method should never block.

Parameters:

event - to represent the completion of a ciphertext file creation which is ready for multipart upload to S3.

onCompletion

public CompleteMultipartUploadResult onCompletion(List<PartETag> partETags)

Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) when all parts have been successfully uploaded to S3. This method is responsible for finishing off the upload by making a complete multi-part upload request to S3 with the given list of etags.

Parameters:

partETags - all the etags returned from S3 for the previous part uploads.

Returns:

the completed multi-part upload result

onAbort

public void onAbort()

Notified from AmazonS3EncryptionClient.uploadObject(UploadObjectRequest) when failed to upload any part. This method is responsible for cancelling ongoing uploads and aborting the multi-part upload request.

newUploadPartRequest

protected UploadPartRequest newUploadPartRequest(PartCreationEvent event,
                                                 File part)

Creates and returns an upload-part request corresponding to a ciphertext file upon a part-creation event.

Parameters:

event - the part-creation event of the ciphertxt file.

part - the created ciphertext file corresponding to the upload-part

uploadPart

protected UploadPartResult uploadPart(UploadPartRequest reqUploadPart)

Uploads the ciphertext via the non-encrypting s3 client.

Parameters:

reqUploadPart - part upload request

Returns:

the result of the part upload when there is no exception

appendUserAgent

protected <X extends AmazonWebServiceRequest> X appendUserAgent(X request,
                                                                String userAgent)

Appends the given user agent to the given request.

Returns:

the given request.

getFutures

public List<Future<UploadPartResult>> getFutures()

getRequest

protected UploadObjectRequest getRequest()

Returns the request initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)

getUploadId

protected String getUploadId()

Returns the upload id after the multi-part upload has been initiated via UploadObjectObserver.onUploadInitiation(UploadObjectRequest)

getS3DirectSpi

protected S3DirectSpi getS3DirectSpi()

Returns the S3DirectSpi instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)

getAmazonS3

protected AmazonS3 getAmazonS3()

Returns the AmazonS3 instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)

getExecutorService

protected ExecutorService getExecutorService()

Returns the ExecutorService instance initialized via UploadObjectObserver.init(UploadObjectRequest, S3DirectSpi, AmazonS3, ExecutorService)