com.amazonaws.mobileconnectors.s3.transferutility

Class TransferUtility

java.lang.Object

com.amazonaws.mobileconnectors.s3.transferutility.TransferUtility

public class TransferUtility
extends java.lang.Object

The transfer utility is a high-level class for applications to upload and download files. It inserts upload and download records into the database and starts a Service to execute the tasks in the background. Here is the usage:

 // Initializes TransferUtility
 TransferUtility transferUtility = new TransferUtility(s3, getApplicationContext());
 // Starts a download
 TransferObserver observer = transferUtility.download("bucket_name", "key", file);
 observer.setTransferListener(new TransferListener() {
     public void onStateChanged(int id, String newState) {
         // Do something in the callback.
     }

     public void onProgressChanged(int id, long bytesCurrent, long bytesTotal) {
         // Do something in the callback.
     }

     public void onError(int id, Exception e) {
         // Do something in the callback.
     }
 });
 

For pausing and resuming tasks:

 // Gets id of the transfer.
 int id = observer.getId();

 // Pauses the transfer.
 transferUtility.pause(id);
 
 // Pause all the transfers.
 transferUtility.pauseAllWithType(TransferType.ANY);

 // Resumes the transfer.
 transferUtility.resume(id);
 
 // Resume all the transfers.
 transferUtility.resumeAllWithType(TransferType.ANY);
 
 

For canceling and deleting tasks:

 // Cancels the transfer.
 transferUtility.cancel(id);
 
 // Cancel all the transfers.
 transferUtility.cancelAllWithType(TransferType.ANY);

 // Deletes the transfer.
 transferUtility.delete(id);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TransferUtility.Builder Builder class for TransferUtility

Constructor Summary

Constructors

Constructor and Description
TransferUtility(AmazonS3 s3, android.content.Context context) Deprecated. Please use TransferUtility.builder().s3Client(s3).context(context).build()

Method Summary

Modifier and Type	Method and Description
static TransferUtility.Builder	builder() Minimum calls required.
boolean	cancel(int id) Sets a transfer to be canceled.
void	cancelAllWithType(TransferType type) Sets all transfers which have the given type to be canceled.
boolean	deleteTransferRecord(int id) Deletes a transfer record with the given id.
TransferObserver	download(java.lang.String key, java.io.File file) Starts downloading the S3 object specified by the default bucket and the key to the given file.
TransferObserver	download(java.lang.String key, java.io.File file, TransferListener listener) Starts downloading the S3 object specified by the default bucket and the key to the given file.
TransferObserver	download(java.lang.String bucket, java.lang.String key, java.io.File file) Starts downloading the S3 object specified by the bucket and the key to the given file.
TransferObserver	download(java.lang.String bucket, java.lang.String key, java.io.File file, TransferListener listener) Starts downloading the S3 object specified by the bucket and the key to the given file.
TransferObserver	getTransferById(int id) Gets a TransferObserver instance to track the record with the given id.
java.util.List<TransferObserver>	getTransfersWithType(TransferType type) Gets a list of TransferObserver instances which are observing records with the given type.
java.util.List<TransferObserver>	getTransfersWithTypeAndState(TransferType type, TransferState state) Gets a list of TransferObserver instances which are observing records with the given type.
java.util.List<TransferObserver>	getTransfersWithTypeAndStates(TransferType type, TransferState[] states) Gets a list of TransferObserver instances which are observing records with the given type.
boolean	pause(int id) Pauses a transfer task with the given id.
void	pauseAllWithType(TransferType type) Pauses all transfers which have the given type.
TransferObserver	resume(int id) Resumes the transfer task with the given id.
java.util.List<TransferObserver>	resumeAllWithType(TransferType type) Resume all the transfers which are not finished.
TransferObserver	upload(java.lang.String key, java.io.File file) Starts uploading the file to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.File file, CannedAccessControlList cannedAcl) Starts uploading the file to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.File file, ObjectMetadata metadata) Starts uploading the file to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.File file, ObjectMetadata metadata, CannedAccessControlList cannedAcl) Starts uploading the file to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.File file, ObjectMetadata metadata, CannedAccessControlList cannedAcl, TransferListener listener) Starts uploading the file to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.InputStream inputStream) Starts uploading the inputStream to the default bucket, using the given key.
TransferObserver	upload(java.lang.String key, java.io.InputStream inputStream, UploadOptions options) Starts uploading the inputStream to the given bucket, using the given key.
TransferObserver	upload(java.lang.String bucket, java.lang.String key, java.io.File file) Starts uploading the file to the given bucket, using the given key.
TransferObserver	upload(java.lang.String bucket, java.lang.String key, java.io.File file, CannedAccessControlList cannedAcl) Starts uploading the file to the given bucket, using the given key.
TransferObserver	upload(java.lang.String bucket, java.lang.String key, java.io.File file, ObjectMetadata metadata) Starts uploading the file to the given bucket, using the given key.
TransferObserver	upload(java.lang.String bucket, java.lang.String key, java.io.File file, ObjectMetadata metadata, CannedAccessControlList cannedAcl) Starts uploading the file to the given bucket, using the given key.
TransferObserver	upload(java.lang.String bucket, java.lang.String key, java.io.File file, ObjectMetadata metadata, CannedAccessControlList cannedAcl, TransferListener listener) Starts uploading the file to the given bucket, using the given key.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransferUtility

@Deprecated
public TransferUtility(AmazonS3 s3,
                                   android.content.Context context)

Deprecated. Please use TransferUtility.builder().s3Client(s3).context(context).build()

Constructs a new TransferUtility specifying the client to use and initializes configuration of TransferUtility and a key for S3 client weak reference.

Parameters:

s3 - The client to use when making requests to Amazon S3

context - The current context

Method Detail

builder

public static TransferUtility.Builder builder()

Minimum calls required. TransferUtility.builder().s3Client(s3).context(context).build()

Returns:

The builder object to construct a TransferUtility.

download

public TransferObserver download(java.lang.String bucket,
                                 java.lang.String key,
                                 java.io.File file)

Starts downloading the S3 object specified by the bucket and the key to the given file. The file must be a valid file. Directory isn't supported. Note that if the given file exists, it'll be overwritten.

Parameters:

bucket - The name of the bucket containing the object to download.

key - The key under which the object to download is stored.

file - The file to download the object's data to.

Returns:

A TransferObserver used to track download progress and state

download

public TransferObserver download(java.lang.String key,
                                 java.io.File file)

Starts downloading the S3 object specified by the default bucket and the key to the given file. The file must be a valid file. Directory isn't supported. Note that if the given file exists, it'll be overwritten.

Parameters:

key - The key under which the object to download is stored.

file - The file to download the object's data to.

Returns:

A TransferObserver used to track download progress and state

download

public TransferObserver download(java.lang.String bucket,
                                 java.lang.String key,
                                 java.io.File file,
                                 TransferListener listener)

Starts downloading the S3 object specified by the bucket and the key to the given file. The file must be a valid file. Directory isn't supported. Note that if the given file exists, it'll be overwritten.

Parameters:

bucket - The name of the bucket containing the object to download.

key - The key under which the object to download is stored.

file - The file to download the object's data to.

listener - a listener to attach to transfer observer.

Returns:

A TransferObserver used to track download progress and state

download

public TransferObserver download(java.lang.String key,
                                 java.io.File file,
                                 TransferListener listener)

Starts downloading the S3 object specified by the default bucket and the key to the given file. The file must be a valid file. Directory isn't supported. Note that if the given file exists, it'll be overwritten.

Parameters:

key - The key under which the object to download is stored.

file - The file to download the object's data to.

listener - a listener to attach to transfer observer.

Returns:

A TransferObserver used to track download progress and state

upload

public TransferObserver upload(java.lang.String bucket,
                               java.lang.String key,
                               java.io.File file)

Starts uploading the file to the given bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

bucket - The name of the bucket to upload the new object to.

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.File file)

Starts uploading the file to the default bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String bucket,
                               java.lang.String key,
                               java.io.File file,
                               CannedAccessControlList cannedAcl)

Starts uploading the file to the given bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

bucket - The name of the bucket to upload the new object to.

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

cannedAcl - The canned ACL to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.File file,
                               CannedAccessControlList cannedAcl)

Starts uploading the file to the default bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

cannedAcl - The canned ACL to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String bucket,
                               java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata)

Starts uploading the file to the given bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

bucket - The name of the bucket to upload the new object to.

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata)

Starts uploading the file to the default bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String bucket,
                               java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata,
                               CannedAccessControlList cannedAcl)

Starts uploading the file to the given bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

bucket - The name of the bucket to upload the new object to.

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

cannedAcl - The canned ACL to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata,
                               CannedAccessControlList cannedAcl)

Starts uploading the file to the default bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

cannedAcl - The canned ACL to associate with this object

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String bucket,
                               java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata,
                               CannedAccessControlList cannedAcl,
                               TransferListener listener)

Starts uploading the file to the given bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

bucket - The name of the bucket to upload the new object to.

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

cannedAcl - The canned ACL to associate with this object

listener - a listener to attach to transfer observer.

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.File file,
                               ObjectMetadata metadata,
                               CannedAccessControlList cannedAcl,
                               TransferListener listener)

Starts uploading the file to the default bucket, using the given key. The file must be a valid file. Directory isn't supported.

Parameters:

key - The key in the specified bucket by which to store the new object.

file - The file to upload.

metadata - The S3 metadata to associate with this object

cannedAcl - The canned ACL to associate with this object

listener - a listener to attach to transfer observer.

Returns:

A TransferObserver used to track upload progress and state

upload

public TransferObserver upload(java.lang.String key,
                               java.io.InputStream inputStream)
                        throws java.io.IOException

Starts uploading the inputStream to the default bucket, using the given key.

Parameters:

key - The key in the specified bucket by which to store the new object.

inputStream - The input stream to upload.

Returns:

A TransferObserver used to track upload progress and state

Throws:

java.io.IOException

upload

public TransferObserver upload(java.lang.String key,
                               java.io.InputStream inputStream,
                               UploadOptions options)
                        throws java.io.IOException

Starts uploading the inputStream to the given bucket, using the given key.

Parameters:

key - The key in the specified bucket by which to store the new object.

inputStream - The input stream to upload.

options - An UploadOptions which hold all of the optional parameters i.e. bucket, metadata, cannedAcl and transferListener.

Returns:

A TransferObserver used to track upload progress and state

Throws:

java.io.IOException

getTransferById

public TransferObserver getTransferById(int id)

Gets a TransferObserver instance to track the record with the given id.

Parameters:

id - A transfer id.

Returns:

The TransferObserver instance which is observing the record.

getTransfersWithType

public java.util.List<TransferObserver> getTransfersWithType(TransferType type)

Gets a list of TransferObserver instances which are observing records with the given type.

Parameters:

type - The type of the transfer "any".

Returns:

A list of TransferObserver instances.

getTransfersWithTypeAndState

public java.util.List<TransferObserver> getTransfersWithTypeAndState(TransferType type,
                                                                     TransferState state)

Gets a list of TransferObserver instances which are observing records with the given type.

Parameters:

type - The type of the transfer.

state - The state of the transfer.

Returns:

A list of TransferObserver of transfer records with the given type and state.

getTransfersWithTypeAndStates

public java.util.List<TransferObserver> getTransfersWithTypeAndStates(TransferType type,
                                                                      TransferState[] states)

Gets a list of TransferObserver instances which are observing records with the given type.

Parameters:

type - The type of the transfer.

states - A list of the the transfer states.

Returns:

A list of TransferObserver of transfer records with the given type and state.

pause

public boolean pause(int id)

Pauses a transfer task with the given id.

Parameters:

id - A transfer id specifying the transfer to be paused

Returns:

Whether successfully paused

pauseAllWithType

public void pauseAllWithType(TransferType type)

Pauses all transfers which have the given type.

Parameters:

type - The type of transfers

resume

public TransferObserver resume(int id)

Resumes the transfer task with the given id. You can resume a transfer in paused, canceled or failed state. If a transfer is in waiting or in progress state but it isn't actually running, this operation will force it to run.

Parameters:

id - A transfer id specifying the transfer to be resumed

Returns:

A TransferObserver of the resumed upload/download or null if the ID does not represent a paused transfer

resumeAllWithType

public java.util.List<TransferObserver> resumeAllWithType(TransferType type)

Resume all the transfers which are not finished. You can resume a transfer in paused, canceled or failed state. If a transfer is in waiting or in progress state but it isn't actually running, this operation will force it to run.

Parameters:

type - The type of transfers

Returns:

A list of TransferObserver objects of the resumed upload/download or null if the ID does not represent a paused transfer

cancel

public boolean cancel(int id)

Sets a transfer to be canceled. Note the TransferState must be TransferState.CANCELED before the transfer is guaranteed to have stopped, and can be safely deleted

Parameters:

id - A transfer id specifying the transfer to be canceled

Returns:

Whether the transfer was set to be canceled.

cancelAllWithType

public void cancelAllWithType(TransferType type)

Sets all transfers which have the given type to be canceled. Note the TransferState must be TransferState.CANCELED before the transfer is guaranteed to have stopped, and can be safely deleted

Parameters:

type - The type of transfers

deleteTransferRecord

public boolean deleteTransferRecord(int id)

Deletes a transfer record with the given id. It just deletes the record but does not stop the running thread, so you must cancel the task before deleting the record.

Parameters:

id - A transfer id specifying the transfer to be deleted.

Returns:

true if at least one record was deleted