edit-icon download-icon

Initialization

Last Updated: Apr 04, 2018

The OSSClient is the Android client of OSS. It provides the caller with a series of methods to operate and manage the buckets and objects. Before you use the OSS Android SDK to initiate a request to OSS, you must first initialize an OSSClient instance and complete necessary settings.

Make sure that the life cycle of the OSSClient is consistent with that of the application. Create a global OSSClient when an application starts, and destroy it when the application ends.

Determine an endpoint

An endpoint is the address of Alibaba Cloud OSS in a region. It supports the following two formats:

Endpoint type Description
OSS region address Address of the region where an OSS bucket is located. For more information about the endpoints in various regions, see here.
User-defined domain name Domain name defined by the user, with the CNAME directing to the OSS domain

For more information about endpoints, click to view details.

OSS region address

You can use one of the following two methods to search for an endpoint mapped to the address of the region where an OSS bucket is located:

  • You can query the mapping relationship between the endpoint and the region. For more information, click to view details.
  • You can log on to Alibaba Cloud OSS Console, open the Bucket Overview page, and find the suffix of the bucket domain. For example, the suffix oss-cn-hangzhou.aliyuncs.com of the bucket domain bucket-1.oss-cn-hangzhou.aliyuncs.com is the endpoint of the bucket on the Internet.

CNAME

You can bind your domain to a bucket through the CNAME and access the objects in the bucket through the domain.

For example, you want to bind the domain new-image.xxxxx.com to a bucket named “image” in the Shenzhen region: you must contact your domain hosting provider for xxxxx.com to configure a new domain name resolution record used to resolve http://new-image.xxxxx.com to http://image.oss-cn-shenzhen.aliyuncs.com. The record type is CNAME.

Configure the endpoint and credential

A mobile client is an untrusted environment. An extremely high risk occurs if you store the AccessKeyId and AccessKeySecret in a mobile client for signing requests. We recommend you use STS Authentication Mode or Self-signed Mode. For more information, see Resource Access Management and Direct Transfer on a Mobile client.

If you are using STS authentication mode, we recommend you use OSSAuthCredentialsProvider to access the application server. Expired tokens are updated automatically.

For more information, click here.

An example of EndPoint and CredentialProvider settings is shown as follows:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. String stsServer = "http://abc.com is an example of an STS application server address."
  3. //We recommend you use OSSAuthCredentialsProvider because expired tokens can be updated quickly.
  4. OSSCredentialProvider credentialProvider = new OSSAuthCredentialsProvider(stsServer);
  5. //If this configuration class is not set, default configuration applies. For more information, see description of the class.
  6. ClientConfiguration conf = new ClientConfiguration();
  7. conf.setConnectionTimeout(15 * 1000); // Connection time-out. The default value is 15 seconds.
  8. conf.setSocketTimeout(15 * 1000); // Socket time-out. The default value is 15 seconds.
  9. conf.setMaxConcurrentTaskNum(5); // The maximum number of concurrent requests. The default value is 5.
  10. conf.setMaxErrorRetry(2); // The maximum number of retries after a failure. The default value is 2.
  11. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

Note: For more authentication modes, see Resource Access Management.

Configure the endpoint according to the CNAME

If you have bound the CNAME to the bucket, you can direct the endpoint to the CNAME directly. For example,

  1. String endpoint = "http://new-image.xxxxx.com";
  2. ...
  3. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

For more authentication modes, see Resource Access Management.

Enable logs

Mobile terminals have complicated environments during usage. The OSS SDK may fail to function in a region or during a period of time. To help developers locate issues, the OSS SDK records some logs to a local directory after the log feature is enabled. To enable the log feature, you must initialize the OSSClient before using it, by calling the following method.

Supplemental instructions:

  • Log files are stored on the SD card at \OSSLog\logs.csv.
  • You can upload the file to the server to further trace the issue.
  • You can also upload the log files after connecting to Alibaba Cloud Log Service. Go to Log Service.
  1. //The log style.
  2. //You can call the OSSLog.enableLog() method to enable displaying logs in the console.
  3. //This setting also supports saving one copy of the log file to the SD card of the mobile phone at \OSSLog\logs.csv. This setting is not enabled by default.
  4. //The log records the request data, returned data and exceptions of OSS operations.
  5. //Such as requestId and response header. The following is a log record case.
  6. //android_version: 5.1. The Android version
  7. //mobile_model: XT1085 . The Android phone model
  8. //network_state: connected. The network status
  9. //network_type: WIFI. The network connection type
  10. //Specific operation information:
  11. //[2017-09-05 16:54:52] - Encounter local exception: //java.lang.IllegalArgumentException: The bucket name is invalid.
  12. //A bucket name must:
  13. //1) be comprised of lower-case characters, numbers, or dash(-);
  14. //2) start with lower case or numbers;
  15. //3) be between 3-63 characters long.
  16. //------>end of log
  17. OSSLog.enableLog(); //Call this method to enable logs.

Set network parameters

You can set detailed ClientConfiguration during the initialization process as follows:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. // We recommend you initialize OSSClient using STS on the mobile client. For more information, see: [Resource Access Management].
  3. OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
  4. ClientConfiguration conf = new ClientConfiguration();
  5. conf.setConnectionTimeout(15 * 1000); // Connection time-out. The default value is 15 seconds.
  6. conf.setSocketTimeout(15 * 1000); // Socket time-out. The default value is 15 seconds.
  7. conf.setMaxConcurrentTaskNum(5); // The maximum number of concurrent requests. The default value is 5.
  8. conf.setMaxErrorRetry(2); // The maximum number of retries after a failure. The default value is 2.
  9. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);

Synchronous and asynchronous interfaces in the SDK

Network requests are not allowed to be processed in the UI thread in mobile development, so most SDK interfaces support synchronous and asynchronous calls to handle requests. After it has been called, the synchronous interface blocks other requests while waiting for the returned results. The asynchronous interface has to import a callback function that processes the result of requests.

Synchronous interfaces cannot be called on the UI thread. If a ClientException or ServiceException occurs, it is thrown immediately. ClientException refers to local exceptions, including network exceptions, invalid parameters, and so on. ServiceException refers to service exceptions returned by OSS, such as authentication failures and server errors, among others.

If an exception occurs while an asynchronous request is being processed, it is handled by a callback function.

When an asynchronous interface is called, the function returns a task. You can cancel a task, wait for it to finish, or get the results directly. For example:

  1. OSSAsyncTask task = oss.asyncGetObejct(...);
  2. task.cancel(); // Cancel the task
  3. task.waitUntilFinished(); // Wait until the task is finished
  4. GetObjectResult result = task.getResult(); // Block other requests and wait for the returned results

The interface supports both the synchronous and asynchronous call methods. For simplicity, this document only provides examples of how to call important interfaces in synchronous and asynchronous modes. For other interfaces, only asynchronous call examples are provided.

Set whether to enable the DNS settings

  1. ClientConfiguration conf = new ClientConfiguration();
  2. conf.setHttpDnsEnable(true);//The default value is "true", meaning enable. To disable the feature, set the value to "false".

Set the custom user-agent

  1. ClientConfiguration conf = new ClientConfiguration();
  2. //The set ua is added to the end of the default ua of the SDK by default. Use the last ua value.
  3. conf.setUserAgentMark("customUserAgent");
Thank you! We've received your feedback.