Introducing the Transfer Utility for the AWS SDK for Android

Last year, as part of the Version 2 release of the AWS Mobile SDK for Android, we introduced the ability to pause and resume transfers. Since then, we have received helpful feedback from the community, and learned more about the needs of mobile developers like you. Today we are pleased to announce the introduction of a new and easier way to transfer data between your Android app and Amazon S3, the S3 Transfer Utility for the AWS SDK for Android.

What is difference between the Transfer Utility and the Transfer Manager?

The Transfer Utility is a new client, with many of the same features as the Transfer Manager, but designed to be simpler and more efficient to use.

Some of the feature enhancements include:

• It uses the local SQLite database to persist all metadata about transfers, allowing them to be paused and resumed without the developer having to serialize or persist any data.
• It utilizes native Android Services so you don’t have to worry about threading or the app being killed.
• It automatically pauses and resumes transfers when internet connectivity is lost and regained.
• It has general configuration improvements for performance with S3 on mobile.

The detailed differences are described in the sections below.

Uploading and Downloading

The Transfer Manager has APIs that support the use of I/O streams. With these APIs, pausing and resuming was not possible. Additionally, you had to specify the content size ahead of time, further reducing the usefulness of streams. With the Transfer Utility there is one file based API for uploading and downloading, which you can always pause or resume (on top of the automatic pause and resume functionality described below).

TransferObserver observer = transferUtility.upload(
MY_BUCKET,           // The S3 bucket to upload to
OBJECT_KEY,          // The key for the uploaded object
FILE_TO_UPLOAD       // The location of the file to be uploaded
);

Downloading is equally simple:

TransferObserver observer = transferUtility.download(
MY_BUCKET,           // The S3 bucket to download from
OBJECT_KEY,          // The key for the object to download
FILE_TO_UPLOAD       // The name of the file to download
); 

Tracking Transfer Progress

The Transfer Utility makes tracking transfers more mobile friendly. The primary way of tracking transfers is through instances of the TransferObserver class. TransferObserver instances are returned from the download() and upload() methods. They are automatically saved to local storage and can be queried for based on id, type (upload, download, or any), or state (such as paused) from anywhere within the app as shown below.

public TransferObserver getTransferById(int id)
public List<TransferObserver> getTransfersWithType(TransferType type) 
public List<TransferObserver> getTransfersWithTypeAndState(TransferType type, TransferState state)

TransferObservers gives access to the state, the total bytes transferred thus far, the total bytes to transfer (for easily calculating progress bars), and a unique ID you can use to keep track of distinct transfers. You can also specify a TransferListener, which will be updated on state or progress change, as well as if an error occurs.

transferObserver.setTransferListener(new TransferListener() {

@Override
public void onStateChanged(int id, TransferState state){
//Do something on state change
}

@Override
public void onProgressChanged(int id, long bytesCurrent, long bytesTotal) {
//Do something on progress change.
}

@Override
public void onError(int id, Exception ex) {
//Do something on error
}
});

Pausing Transfers

With the Transfer Manager, there is no guarantee a transfer can be paused, and there are multiple ways to attempt to pause. Also, pauses require developers to serialize metadata about the transfer to persistent storage which they must manage.
The Transfer Utility handles persisting of all transfer metadata for you. If an app is killed, crashes, or loses internet connectivity, transfers are automatically paused. You can manually pause a transfer by id with pause(transferId), pause all downloads (or uploads) with pauseAllWithType(TransferType.DOWNLOAD), or pause all transfers with pauseAllWithType(TransferType.ANY).

Resuming Transfers

The Transfer Utility automatically pauses transfers in many scenarios. In the case that your transfer was paused due to loss of network connectivity, it will automatically resume when the network is available again. In the case that the transfer is manually paused, or the app is killed, it can be resumed with the resume(transferId) method.

Summary and Transfer Manager deprecation plan

Overall, we have built the Transfer Utility as an improvement and simplification over the Transfer Manager. We believe it fits better with the needs of customers and helps accelerate high quality app development.

The Transfer Utility will replace the Transfer Manager, and going forward the Transfer Manager will be deprecated. To help customers migrate from the Transfer Manager to the new Transfer Utility, we have posted a migration guide.

Additional help, and request for feedback

The step by step Getting Started Guide

The Sample on GitHub

The latest SDK API Reference

As always, we really appreciate community feedback: as a comment on this blog, a post on our forums, or as a GitHub issue.