This document mainly describes how to install and use the OSS Android SDK. This document assumes that you have already activated the Alibaba Cloud OSS service and created an AccessKeyID and an AccessKeySecret. In the document, ID refers to the AccessKeyID and KEY indicates the AccessKeySecret. If you have not yet activated or do not know about the OSS service, log on to the OSS Product Homepage for more help.
- Android 2.3 or above
- You must have registered an Alibaba Cloud account with the OSS activated.
OSS Android SDK is dependent on OkHttp.
You can introduce the downloaded JAR package into the project, or you can use it through the Maven dependency.
After you download the OSS Android SDK ZIP package, perform the following steps (applicable to Android Studio and Eclipse):
- On the official website, click to view details to download the SDK package
- Unzip the SDK package in the libs directory to obtain the following JAR packages: aliyun-oss-sdk-android-2.3.0.jar, okhttp-3.x.x.jar and okio-1.x.x.jar
- Import the three JAR packages to the libs directory of the project
compile 'com.aliyun.dpa:oss-android-sdk:+'
You can run the gradle command for packaging after cloning the project source code:
# Clone the project
$ git clone https://github.com/aliyun/aliyun-oss-android-sdk.git
# Enter the directory
$ cd aliyun-oss-android-sdk/
# Run the packaging script. JDK 1.7 is required
$ ./gradlew releaseJar
# Enter the directory generated after packaging and the JAR package will be generated in this directory
$ cd build/libs && lsThe following are the Android permissions needed by the OSS Android SDK. Please make sure these permissions are already set in your AndroidManifest.xml file. Otherwise, the SDK will not work normally.
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
Because network requests cannot be processed on the UI thread in mobile development scenarios, many interfaces of the SDK support synchronous and asynchronous calls to handle requests. After being called, the synchronous interface block other requests while waiting for the returned results, whereas the asynchronous interface imports a callback function in the request to return the request processing results.
The UI thread does not support synchronous interface calls. ClientException or ServiceException will be thrown in the event of an exception. ClientException indicates a local exception, such as a network exception or invalid parameters. ServiceException indicates a service exception returned by the OSS, such as an authentication failure or a server error.
When an exception occurs during asynchronous request processing, the exception will be handled by a callback function.
When an asynchronous interface is called, the function will return a task directly. You can cancel the task, wait till the task is finished, or obtain results directly. For example, you can
OSSAsyncTask task = oss.asyncGetObject(...);
task.cancel(); // Cancel the task
task.waitUntilFinished(); // Wait till the task is finished
GetObjectResult result = task.getResult(); // Block other requests and wait for the returned resultsThe basic object upload and download processes are demonstrated below. For details, you can refer to the following directories of this project:
The test directory: click to view details
or
the sample directory: click to view details.
We recommend STS authentication mode to initialize the OSSClient on mobile. For details about authentication, refer to the Access Control section.
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
//if null , default will be init
ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // connction time out default 15s
conf.setSocketTimeout(15 * 1000); // socket timeout，default 15s
conf.setMaxConcurrentRequest(5); // synchronous request number，default 5
conf.setMaxErrorRetry(2); // retry，default 2
OSSLog.enableLog(); //write local log file ,path is SDCard_path\OSSLog\logs.csv
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);Suppose you already have a bucket in the OSS console. You can use the following code to upload a local file to OSS:
// Construct an upload request
PutObjectRequest put = new PutObjectRequest("<bucketName>", "<objectKey>", "<uploadFilePath>");
// You can set progress callback during asynchronous upload
put.setProgressCallback(new OSSProgressCallback<PutObjectRequest>() {
@Override
public void onProgress(PutObjectRequest request, long currentSize, long totalSize) {
Log.d("PutObject", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
OSSAsyncTask task = oss.asyncPutObject(put, new OSSCompletedCallback<PutObjectRequest, PutObjectResult>() {
@Override
public void onSuccess(PutObjectRequest request, PutObjectResult result) {
Log.d("PutObject", "UploadSuccess");
}
@Override
public void onFailure(PutObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
// Request exception
if (clientExcepion != null) {
// Local exception, such as a network exception
clientExcepion.printStackTrace();
}
if (serviceException != null) {
// Service exception
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});
// task.cancel(); // Cancel the task
// task.waitUntilFinished(); // Wait till the task is finishedThe following code downloads the specified object (you need to handle the input stream of the returned data):
// Construct an object download request
GetObjectRequest get = new GetObjectRequest("<bucketName>", "<objectKey>");
OSSAsyncTask task = oss.asyncGetObject(get, new OSSCompletedCallback<GetObjectRequest, GetObjectResult>() {
@Override
public void onSuccess(GetObjectRequest request, GetObjectResult result) {
// Request succeeds
Log.d("Content-Length", "" + getResult.getContentLength());
InputStream inputStream = result.getObjectContent();
byte[] buffer = new byte[2048];
int len;
try {
while ((len = inputStream.read(buffer)) != -1) {
// Process the downloaded data
}
} catch (IOException e) {
e.printStackTrace();
}
}
@Override
public void onFailure(GetObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
// Request exception
if (clientExcepion != null) {
// Local exception, such as a network exception
clientExcepion.printStackTrace();
}
if (serviceException != null) {
// Service exception
Log.e("ErrorCode", serviceException.getErrorCode());
Log.e("RequestId", serviceException.getRequestId());
Log.e("HostId", serviceException.getHostId());
Log.e("RawMessage", serviceException.getRawMessage());
}
}
});
// task.cancel(); // Cancel the task
// task.waitUntilFinished(); // Wait till the task is finished as neededThe SDK provides advanced upload, download, resumable upload/download, object management and bucket management features. For details, see the complete official documentation: click to view details
- Apache License 2.0.
- Alibaba Cloud OSS official website.
- Alibaba Cloud OSS official forum.
- Alibaba Cloud OSS official documentation center.
- Alibaba Cloud official technical support: Submit a ticket.
