Amazon Drive SDK for Android Overview
The SDK Client
AmazonCloudDriveClient
The AmazonCloudDriveClient class has methods for reading and writing both metadata and binary data to Amazon Drive. The client is the interface for uploading and downloading files, listing nodes, changing node relationships, and modifying node properties.
AmazonCloudDriveClient client = new AmazonCloudDriveClient(
new AccountConfiguration(
new AmazonAuthorizationConnectionFactory(
mAmazonAuthorizationManager,
Constants.APP_AUTHORIZATION_SCOPES)
),
new ClientConfiguration(Constants.USER_AGENT)
);
Creating a Client
To create an AmazonCloudDriveClient instance, you must use configuration objects.
AccountConfiguration- Modifies the configuration of the states related to the account.ClientConfiguration- Modifies the configuration for all of the other states.
AccountConfiguration
The AccountConfiguration instance is specific to a user account and should be abandoned when the user logs out. AccountConfiguration requires an instance of an AuthenticatedURLConnectionFactory to generate the HttpURLConnections. The provided AmazonAuthorizationConnectionFactory is recommended when using Login with Amazon. For more information on how to create an instance of the AmazonAuthorizationManager, see the Use SDK for Android section of the Login with Amazon documentation.
Endpoints Cache
The AccountConfiguration can optionally be configured to use an EndpointsCache. The EndpointsCache holds Amazon Drive endpoints so they are not required to be resolved for every request. If an EndpointsCache instance is not provided, then the SimpleEndpointsCache instance is used.
ClientConfiguration
ClientConfiguration is not specific to an account and may be used again if the user signs out. The ClientConfiguration must be include a user agent string, so that the instance of the AmazonCloudDriveClient is able to be identified by Amazon Drive. A MetricListener can be set on the instance of the ClientConfiguration in order to observe metrics from the client.
Making a Request
Constructing a Request
To make a request using the client, you must create an instance of the request object for that API. Example: If you want to send and uploadFile() method request, then you must create an instance of UploadFileRequest. All of the required parameters for the request are part of the constructor method for the request object. Any optional parameters for the request may be set on request object with additional set or modify methods.
// The constructor specifies required parameters for a request.
UploadFileRequest uploadFileRequest = new UploadFileRequest(nodeName, new FileInputStream(file), file.length());
// Add optional parameters using set or modify to a request.
uploadFileRequest.setParents(parents);
uploadFileRequest.setSuppress(Suppress.Deduplication);
// Send a synchronous request.
UploadFileResponse response = client.uploadFile(uploadFileRequest, uploadProgressListener);
Sending Requests and Handling Errors
AmazonCloudDriveClient APIs come in two flavors: synchronous and asynchronous. The synchronous methods block the calling thread until the operation completes and should not be called from the UI thread. The asynchronous methods run on the provided ExecutorService (or a default, if none is provided) and do not block the requesting thread. The asynchronous methods are identified by the Async part of the method name.
Synchronous Methods
A synchronous method either returns a response object or void. All errors are thrown as exceptions. If no exception is thrown, then you may assume that the request was successful.
// Example of synchronous listNodes method request.
ListNodesResponse response = client.listNodes(request);
Asynchronous Methods
An asynchronous method reports the results with the AsyncHandler callback method. Alternatively, your app can use the result of the Future.get() to get the result.
Future<ListNodesResponse> futureListNodesResponse = mAmazonCloudDriveClient.listNodesAsync(listNodesRequest, new AsyncHandler<ListNodesRequest, ListNodesResponse>() {
@Override
public void onSuccess(ListNodesRequest listNodesRequest, ListNodesResponse listNodesResponse) {
// Handle success case
// listNodesResponse is available
}
@Override
public void onError(ListNodesRequest listNodesRequest, Exception e) {
// Handle exception
}
@Override
public void onCanceled(ListNodesRequest listNodesRequest) {
// Handle cancellation
}
});
Keep in mind that making an anonymous class instance holds a strong reference to the enclosing class. If the AsyncHandler is declared inside of an Activity or other object that has a lifecycle that is not in your control, consider making a non-anonymous instance to avoid leaks.
Paginated Requests
Listing calls are paginated so that no more than 200 nodes are returned at a time. Paginated requests take a continuation token to continue to the next page of results. A null continuation token is used to get the first page.
// ListChildren is an example of a paged request. We may not get all
// of the nodes back in one request, so we will need to keep looping
// until we get all of the a null next token as a response.
String nextToken = null;
do {
// Make a synchronous (blocking) call to Amazon Drive that lists
// all of the children for the node.
ListChildrenRequest listChildrenRequest = new ListChildrenRequest(id);
listChildrenRequest.setStartToken(nextToken);
ListChildrenResponse response = mAmazonCloudDriveClient.listChildren(listChildrenRequest);
nextToken = response.getNextToken();
List<Node> nodes = response.getData();
// ... do something with the nodes ..
}
while (nextToken != null);
Retry / Backoff
There are two kinds of exceptions that can result from a request to Amazon Drive: retryable and non-retryable exceptions. AmazonCloudDriveClient automatically retries retryable exceptions and backoff exponentially. The number of times that the client should retry is configurable by calling setMaxErrorRetry() on the ClientConfiguration object.
Support
If you have any questions, see the Developer Forum.