Giter VIP home page Giter VIP logo

aliyun-oss-android-sdk's Introduction

Alibaba Cloud OSS SDK for Android

README of Chinese

Introduction

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.

Environment requirements

  • Android 2.3 or above
  • You must have registered an Alibaba Cloud account with the OSS activated.

Installation

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.

Introduce the JAR package directly

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

Gradle via JCenter

compile 'com.aliyun.dpa:oss-android-sdk:+'

Compile the JAR package from the source code

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 && ls

Javadoc

Click to view details.

Configure permissions

The 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>

Descriptions of synchronous interfaces and asynchronous interfaces in the SDK

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 results

Quick start

The 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.

Step-1. Initialize the OSSClient

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);

Step-2. Upload a file

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 finished

Step-3. Download a specified object

The 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 needed

Complete documentation

The 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

License

  • Apache License 2.0.

Contact us

aliyun-oss-android-sdk's People

Contributors

1019272778 avatar baiyubin2020 avatar binghaiwang avatar chenjie1979 avatar duan007a avatar github1019272778 avatar imliujun avatar luozhang002 avatar qixu001 avatar sdlcdhc avatar sducodemonkey avatar wushuai1415 avatar xuyecan avatar

Stargazers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.