Object management

Updated at：2025-11-03

Upload Object

Simplest upload

Basic workflow
1. Instantiate the BOSClient class.
2. The BOSClient.putObject() method allows objects to be uploaded in four ways: file, data stream, binary string, and plain string.
3. For the returned PutObjectResponse instance, call getETag() to get the successfully uploaded ETag.

Example code

                Java
                
            

                // Get specified file
 File file = new File(<FilePath>);     //Specify the file path
 // Upload object as a file
PutObjectResponse putObjectFromFileResponse =
    client.putObject(<BucketName>, <ObjectKey>, file);
 // Obtain data stream
InputStream inputStream = new FileInputStream(<FilePath>);
 // Upload an object in the form of a data stream
PutObjectResponse putObjectResponseFromInputStream =
    client.putObject(<BucketName>, <ObjectKey>, inputStream);
 // Upload object as binary string
PutObjectResponse putObjectResponseFromByte =
    client.putObject(<BucketName>, <ObjectKey>, <byte>);
 // Upload object in string form
PutObjectResponse putObjectResponseFromString =
    client.putObject(<BucketName>, <ObjectKey>, <string>);
 // Print ETag
System.out.println(putObjectFromFileResponse.getETag());
            

Plain Text

1> **Note**: Objects are uploaded to BOS as files, and the putObject function supports uploading objects with a size not exceeding 5GB. After the putObject request is processed successfully, BOS will return the ETag of the object in the Header as the file identifier.

Complete example

                Java
                
            

                import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.development.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.PutObjectResponse;
​    
public class ExampleActivity extends Activity {
  private String bucketName = <BucketName>;
  private String objectKey = <ObjectKey>;
  byte[] b = null;
  String str = <PutString>;
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Get specified file
                File file = new File("/path/to/file.zip");
 // Upload object as a file
                PutObjectResponse putObjectFromFileResponse = client.putObject(<BucketName>, <ObjectKey>, file);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Upload an object in the form of a data stream
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(<BucketName>, <ObjectKey>, inputStream);
 // Upload object as binary string
                PutObjectResponse putObjectResponseFromByte = client.putObject(<BucketName>, <ObjectKey>, b);
 // Upload object in string form
                PutObjectResponse putObjectResponseFromString = client.putObject(<BucketName>, <ObjectKey>, str);
 // Print ETag
                System.out.println(putObjectFromFileResponse.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Set the Copy attributes of an object

The CopyObject API copies an existing object to a new one. During the process, it checks the source object's ETag or modification status to decide whether to proceed with the operation. The detailed parameters are as follows:

Name	Types	Description	Whether required
x-bce-copy-source-if-match	String	If the ETag value of the source object matches the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
x-bce-copy-source-if-none-match	String	If the ETag value of the source object does not match the ETag value provided by the user, the copy operation is performed; otherwise, it fails.	No
x-bce-copy-source-if-unmodified-since	String	If the source object has not been modified since x-bce-copy-source-if-unmodified-since, the copy operation will proceed; otherwise, it will fail.	No
x-bce-copy-source-if-modified-since	String	If the source object has been modified since x-bce-copy-source-if-modified-since, the copy operation will proceed; otherwise, it will fail.	No

Example code

                Java
                
            

                // Initialize BosClient
BosClient client = ...;
 // Create CopyObjectRequest object
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketName, srcKey, destBucketName, destKey);
 // Set new Metadata
Map<String, String> userMetadata = new HashMap<String, String>();
userMetadata.put("<user-meta-key>","<user-meta-value>");
ObjectMetadata meta = new ObjectMetadata();
meta.setUserMetadata(userMetadata);
copyObjectRequest.setNewObjectMetadata(meta);
//copy-source-if-match
copyObjectRequest.withETag("111111111183bf192b57a4afc76fa632");
//copy-source-if-none-match
copyObjectRequest.withNoMatchingETagConstraint("111111111183bf192b57a4afc76fa632");
Date modifiedSinceConstraint = new Date();    
SimpleDateFormat df = new SimpleDateFormat("E, dd MMM yyyy HH:mm:ss z", Locale.UK);  
df.setTimeZone(new java.util.SimpleTimeZone(0, "GMT"));        
String date = df.format(modifiedSinceConstraint);
//copy-source-if-modified-since
copyObjectRequest.withModifiedSinceConstraint(date);
//copy-source-if-unmodified-since
copyObjectRequest.withUnmodifiedSinceConstraint(date);
 // Copy Object
CopyObjectResponse copyObjectResponse = client.copyObject(copyObjectRequest);
            

Set object's HTTP Header

BOS allows setting Http Headers when uploading an object.

Basic workflow
1. Create an ObjectMetadata instance.
2. Use methods like setContentLength() and setContentType() to configure Http Headers.
3. Pass the metadata as a parameter when calling client.putObject().

Example code

                Java
                
            

                // Create an instance of the ObjectMetadata class
ObjectMetadata meta = new ObjectMetadata();
 // Set ContentLength size
meta.setContentLength(<Length>);
 // Set ContentType
meta.setContentType("application/json");
client.putObject(<BucketName>, <ObjectKey>, content, meta);
            

Plain Text

1> **Note:** Headers can be set with attributes such as "Cache-Control", "Content-Encoding", "Content-Disposition", and "Expires"

Complete example

                Java
                
            

                import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ObjectMetadata;
import com.baidubce.services.bos.model.PutObjectResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Create an instance of the ObjectMetadata class
                ObjectMetadata meta = new ObjectMetadata();
 // Set ContentLength size
                meta.setContentLength(1000);
 // Set ContentType
                meta.setContentType("application/json");
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(bucketName, objectKey, inputStream, meta);
 // Print ETag
                System.out.println(putObjectResponseFromInputStream.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

User-defined metadata

BOS supports user-defined metadata for object descriptions.

Basic workflow
1. Create an ObjectMetadata instance.
2. Use the addUserMetadata() method to add custom metadata to the Http Headers.
3. Pass the metadata as a parameter when calling client.putObject().

Example code

                Java
                
                // Set the value of custom metadata name to my-data
meta.addUserMetadata("name", "my-data");	  
 // Upload Object
client.putObject(<BucketName>, <ObjectKey>, <Content>, meta);

Plain Text

1> **Note:** In the provided example, a user-defined metadata property is created with the key "name" and the value "my-data." This metadata can be retrieved when the object is downloaded. Though multiple such parameters can be added, the combined size of all User Metadata must not exceed 2KB.

Complete example

                Java
                
            

                import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ObjectMetadata;
import com.baidubce.services.bos.model.PutObjectResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Obtain data stream
                InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Create an instance of the ObjectMetadata class
                ObjectMetadata meta = new ObjectMetadata();
 // Custom metadata
                meta.addUserMetadata("name", "my-data");	    
                PutObjectResponse putObjectResponseFromInputStream = client.putObject(<BucketName>, <ObjectKey>, inputStream, meta);
 // Print ETag
                System.out.println(putObjectResponseFromInputStream.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (FileNotFoundException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Upload object in append mode

BOS provides an AppendObject feature for uploading files in append mode, making it ideal for scenarios like log appending, live streaming, and real-time video uploads. Objects created via AppendObject belong to the Appendable Objects category, allowing additional data to be appended. In contrast, objects uploaded using PutObject are classified as Normal Objects and do not support data appending. An AppendObject has a size limit between 0 and 5GB.

Example code

                Java
                
            

                public void AppendObject(BosClient client, String bucketName, String objectKey, byte[] byte1, String string1) {
 // Get specified file
      File file = new File("/path/to/file.zip");
 // Obtain data stream
      InputStream inputStream = new FileInputStream("/path/to/test.zip");
 // Upload object as a file
      AppendObjectResponse appendObjectFromFileResponse = client.appendObject(bucketName, objectKey, file);
 // Upload an object in the form of a data stream
      AppendObjectResponse appendObjectResponseFromInputStream = client.appendObject(bucketName, objectKey, inputStream);
 // Upload object as binary string
      AppendObjectResponse appendObjectResponseFromByte = client.appendObject(bucketName, objectKey, byte1);
 // Upload object in string form
      AppendObjectResponse appendObjectResponseFromString = client.appendObject(bucketName, objectKey, string1);
 // Append content to AppendFile
      Long nextOffset = appendObjectFromFileResponse.getNextAppendOffset();
      AppendObjectRequest request =new AppendObjectRequest(bucketName, objectKey,
      RestartableInputStream.wrap(string1.getBytes()));
      request.withOffset(nextOffset);
      AppendObjectResponse appendResponse = client.appendObject(request);      
}
            

Obtain upload progress

The Android SDK supports providing real-time upload progress information during the upload. It currently supports four APIs: PutObject, AppendObject, UploadPart and PutSuperObjectFromFile Using the progress upload interface requires constructing the corresponding Request (PutObjectRequest, AppendObjectRequest, UploadPartRequest and PutSuperObjectRequest).

The SDK offers an upload progress callback API that enables you to define operations to execute during uploads, such as updating the UI.

                Java
                
            

                public interface BceProgressCallback<T extends AbstractBceRequest> {
 // request is the upload request
 // currentSize is the current upload size (unit: byte)
 // totalSize is the total size to be uploaded in this request (unit: byte)
      void onProgress(T request, long currentSize, long totalSize);
｝
            

PutObject example code:

                Java
                
            

                PutObjectRequest request = new PutObjectRequest(this.bucketName, "test", file);
ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
request.setObjectMetadata(objectMetadata);
request.setProgressCallback(new BosProgressCallback<PutObjectRequest>() {
    @Override
    public void onProgress(PutObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
String eTag = this.client.putObject(request).getETag();
            

AppendObject example code:

                Java
                
            

                ObjectMetadata objectMetadata = new ObjectMetadata();
objectMetadata.setContentType("text/plain");
AppendObjectRequest request = new AppendObjectRequest(this.bucketName, "test", file);
request.setObjectMetadata(objectMetadata);
AppendObjectResponse response = this.client.appendObject(request);
Long nextOffset = response.getNextAppendOffset();
request.withOffset(nextOffset);
request.setProgressCallback(new BosProgressCallback<AppendObjectRequest>() {
    @Override
    public void onProgress(AppendObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
response = this.client.appendObject(request);
            

UploadPart example code:

                Java
                
            

                UploadPartRequest request = new UploadPartRequest().withBucketName(this.bucketName)
        .withKey("test").withUploadId(uploadId).withPartNumber(1).withPartSize(8000)
        .withInputStream(fis);
request.setProgressCallback(new BosProgressCallback<UploadPartRequest>() {
    @Override
    public void onProgress(UploadPartRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
UploadPartResponse response = this.client.uploadPart(request);
            

PutSuperObjectFromFile example code:

                Java
                
            

                PutSuperObjectRequest request = new PutSuperObjectRequest().withBucketName(this.bucketName)
        .withKey("test").withPartSize(1024*1024*2L).withFile(file);
request.setProgressCallback(new BosProgressCallback<PutSuperObjectRequest>() {
    @Override
    public void onProgress(PutSuperObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
PutSuperObjectResponse response = this.client.putSuperObjectFromFile(request);
            

By default, the SDK’s upload progress callback granularity is 2,048 bytes. You can adjust the granularity to better suit your application using the provided methods.

BosClientConfiguration config=new BosClientConfiguration(); config.setUploadSegmentPart(1024);

Note: This value must be between 1-8192. If outside this range, Android SDK will forcibly set it to 2048.

Cancellation interface

Android SDK supports canceling this request during the request process. The remaining data in the upload request will not be uploaded to BOS. Canceling the operation in the download request will close the connection, and the executing operation will throw Request is canceled! exception.

All BOS operations support cancellation interfaces, but completed requests cannot be canceled, and no exceptions will be thrown for completed operations

                Java
                
            

                // Take the upload interface cancellation as an example
final PutObjectRequest req = new PutObjectRequest(<BucketName>, <ObjectName>,
         new FileInputStream(<FilePath>));
Runnable cancelTask = new Runnable() {
    @Override
    public void run() {
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            e.printStackTrace()
        }
 // Cancel the current upload request
        req.cancel();
    }
};
new Thread(cancelTask).start();
client.putObject(req);
            

Synchronous callback

The Android SDK supports the BOS server-side synchronous callback API. By setting the process parameter in the PutObjectRequest, the BOS server can actively trigger the callback API after upload completion to notify the client.

                Java
                
            

                PutObjectRequest request = new PutObjectRequest({bucket}, {object}, {inputStream});
 // Set the x-bce-process parameter
request.setProcess({x-bce-process});
PutObjectResponse response = client.putObject(request);
 // Obtain the returned http status code
int statusCode = response.getHttpResponse().getStatusCode();
 // Obtain the data returned by the callback API
string callbackString = response.getServerCallbackReturnBody();
            

View the object in the bucket.

Simple query

View the list of objects in a bucket.

Basic workflow
1. Instantiate the BOSClient class.
2. Calling the BOSClient.listObjects(bucketName) method returns an instance of the ListObjectsResponse class.
3. For the ListObjectsResponse class, methods like getBuckets(), getOwner(), and getMetadata() can be executed.

Example code

                Java
                
            

                // Obtain all object information under the specified bucket
ListObjectsResponse listing = client.listObjects(<BucketName>);
 // Traverse all objects
for (BosObjectSummary objectSummary : listing.getContents()) {
    System.out.println("ObjectKey: " + objectSummary.getKey());
}
            

Plain Text

1> **Note:** The listObjects() method returns a ListObjectsResponse object, which contains the results of this listObject request. Users can obtain the description information of all objects through the getContents method in ListObjectsResponse.
2>
3> -   By default, if the number of objects in the bucket exceeds 1,000, only 1,000 objects will be returned. In this case, the IsTruncated value in the returned result will be set to True, and NextMarker will be provided as the starting point for the next retrieval.
4>
5>
6> -   To retrieve more objects, use the Marker parameter for reading in batches. Refer to [Extended Query](#Extended query).

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.BosObjectSummary;
import com.baidubce.services.bos.model.ListObjectsResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyId>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Obtain all object information under the specified bucket
                ListObjectsResponse listing = client.listObjects(<BucketName>);
 // Traverse all objects
                for (BosObjectSummary objectSummary : listing.getContents()) {
                    System.out.println("ObjectKey: " + objectSummary.getKey());
                }               	                    
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Extended query

Users can configure the ListObjectsRequest parameters to perform advanced query operations. The extended parameters available for configuration in ListObjectsRequest include the following:

Parameter name	Description	Default value
MaxKeys	Specify the maximum number of objects to return, which must not exceed 1,000.	1000
Prefix	Set the prefix of the objectKey. The prefix means that the objectKey contains and starts with the value of Prefix. It is usually used in conjunction with Delimiter when [querying simulated folders](#Query simulated folders).	-
Delimiter	It is a delimiter used to hierarchize objectKey. It is usually used in conjunction with Prefix when [querying simulated folders](#Query simulated folders). The objectKey from the Prefix to the first occurrence of the Delimiter character is called: CommonPrefixes.	-
Marker	It is a string used to set the starting position of the returned results. After setting the Marker value, the returned objects will be returned starting from the Marker value in alphabetical order.	-

Basic workflow
1. Create an instance of the ListObjectsRequest class.
2. Use methods like setDelimiter(), setMarker(), or setPrefix() in ListObjectsRequest to enable more advanced query functionalities.
3. Create an instance of the BOSClient class and invoke the listObjects(listObjectsRequest) method.

Example code

                Java
                
            

                // Construct a ListObjectsRequest request
ListObjectsRequest listObjectsRequest = new ListObjectsRequest(<BucketName>);  
 // Set extended query parameters
listObjectsRequest.setDelimiter(<Delimiter>);
listObjectsRequest.setMarker(<Marker>);
...   
ListObjectsResponse listing = client.listObjects(listObjectsRequest);
            

Plain Text

1> **Note:** The above code calls an overloaded method from `listObjects` by passing a `ListObjectsRequest` to complete the request.

Complete example

Example 1:

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.BosObjectSummary;
import com.baidubce.services.bos.model.ListObjectsRequest;
import com.baidubce.services.bos.model.ListObjectsResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Construct a ListObjectsRequest request
                ListObjectsRequest listObjectsRequest = new ListObjectsRequest(<BucketName>);
 // Set parameters
                listObjectsRequest.setDelimiter("/");
                listObjectsRequest.setMarker("123");
                listObjectsRequest.setMaxKeys(100);
                listObjectsRequest.setPrefix("fun");
 // Obtain all eligible object information under the specified bucket
                ListObjectsResponse listing = client.listObjects(listObjectsRequest);
 // Traverse all objects
                for (BosObjectSummary objectSummary : listing.getContents()) {
                    System.out.println("ObjectKey: " + objectSummary.getKey());
                }                	
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Example II: A complete example using the NextMarker.

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.BosObjectSummary;
import com.baidubce.services.bos.model.ListObjectsRequest;
import com.baidubce.services.bos.model.ListObjectsResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);
  new Thread(new Runnable() {
      @Override
      public void run() {
         try {
            BosClientConfiguration config = new BosClientConfiguration();
            config.setCredentials(new DefaultBceCredentials(<AccessKeyId>, <SecretAccessKey>);
            config.setEndpoint(<EndPoint>);
            BosClient client = new BosClient(config);
            ListObjectsRequest listObjectsRequest = new ListObjectsRequest(<BucketName>);
            listObjectsRequest.setMarker("");
            listObjectsRequest.setMaxKeys(20);
            listObjectsRequest.setDelimiter(BceConfig.BOS_DELIMITER);
            ListObjectsResponse listObjectsResponse = client.listObjects(listObjectsRequest);
            String nextMark = "";
            if(listObjectsResponse.isTruncated()){
               nextMark = listObjectsResponse.getNextMarker();
            }
           ListObjectsRequest listObjectsRequest2 = new ListObjectsRequest(<BucketName>);
           listObjectsRequest2.setMarker(nextMark);
           listObjectsRequest2.setMaxKeys(20);
           listObjectsRequest2.setDelimiter(BceConfig.BOS_DELIMITER);
           ListObjectsResponse listing = client.listObjects(listObjectsRequest2);
           for (BosObjectSummary objectSummary : listing.getContents()) {
               System.out.println("ObjectKey: " + objectSummary.getKey());
            }                
          } catch (BceServiceException e) {
            System.out.println("Error ErrorCode: " + e.getErrorCode());
            System.out.println("Error RequestId: " + e.getRequestId());
            System.out.println("Error StatusCode: " + e.getStatusCode());
            System.out.println("Error Message: " + e.getMessage());
            System.out.println("Error ErrorType: " + e.getErrorType());
         } catch (BceClientException e) {
            System.out.println("Error Message: " + e.getMessage());
         }
      }
    }).start();
}}
            

Query simulated folders

Since BOS is inherently a (<Key>,<Value>) storage system, the concept of "folder" does not exist in principle. However, you can simulate the folder function by combining the Delimiter and Prefix} parameters.

Suppose the bucket contains five files: bos.jpg, fun/, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. The "/" symbol can be used as a delimiter to mimic folder structures.

Recursively list all files under the simulated folder

You can obtain all files under a simulated folder by setting the Prefix parameter:

                Java
                
            

                // Construct a ListObjectsRequest request
ListObjectsRequest listObjectsRequest = new ListObjectsRequest(<BucketName>);
 // Recursively list all files under the fun directory
listObjectsRequest.setPrefix("fun/");
ListObjectsResponse listing = client.listObjects(listObjectsRequest);
 // Traverse all objects
System.out.println("Objects:");
for (BosObjectSummary objectSummary : listing.getContents()) {
   System.out.println(objectSummary.getKey());
}
            

Output:

                Java
                
            

                Objects:
fun/
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg
            

View files and subfolders under the simulated folder

With the combination of Prefix and Delimiter, it can list files and subfolders under the simulated folder:

                Java
                
            

                // Construct a ListObjectsRequest request
ListObjectsRequest listObjectsRequest = new ListObjectsRequest(<BucketName>);
 // Specify "/" as the delimiter for simulated folder
listObjectsRequest.setDelimiter("/");
 // List all files and subfolders under the “fun” folder
listObjectsRequest.setPrefix("fun/");
ListObjectsResponse listing = client.listObjects(listObjectsRequest);
 // Traverse all objects
System.out.println("Objects:");
for (BosObjectSummary objectSummary : listing.getContents()) {
   System.out.println(objectSummary.getKey());
}
 // Traverse all CommonPrefix
System.out.println("\nCommonPrefixs:");
for (String commonPrefix : listing.getCommonPrefixes()) {
   System.out.println(commonPrefix);
}
            

Output:

                Java
                
            

                Objects:
fun/
fun/test.jpg
CommonPrefixs:
fun/movie/
            

Description:

In the returned results, the list under Objects shows the files under the fun folder. The list in CommonPrefixs shows all subfolders under the fun folder. It can be seen that the two files fun/movie/001.avi and fun/movie/007.avi are not listed because they belong to the movie subfolder under the fun folder.

Get Object

Simple object get

Users can load the object into a stream by using the following code.

Basic workflow
1. Instantiate the BOSClient class.
2. By calling the BOSClient.getObject() method, the specified BosObject will be returned.
3. Load the BosObject into a stream for further processing.

Example code

                Java
                
            

                //Obtain the object, with returned result BosObject object
BosObject object = client.getObject(<BucketName>, <ObjectKey>);
 // Retrieve ObjectMeta
ObjectMetadata meta = object.getObjectMetadata();
 //Obtain the object's input stream
InputStream objectContent = object.getObjectContent();
 // Process object
...
 // Close stream
objectContent.close();
            

Plain Text

1> **Note:**
2>
3> -   The BosObject includes various details about the object, such as the bucket it belongs to, the object’s name, metadata, and an input stream. Users can read the object's content into a file or memory by interacting with the input stream.
4> -   ObjectMetadata contains information such as the ETag defined during object upload, HTTP headers, and custom metadata.
5> -   Using the getObjectContent() method of BosObject, users can access the input stream of the returned object, enabling them to read and process the object's content.

Complete example

                Java
                
            

                import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.BosObject;
import com.baidubce.services.bos.model.ObjectMetadata;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 //Obtain the object, with returned result BosObject object
                BosObject object = client.getObject(<BucketName>, <ObjectKey>);
 // Retrieve ObjectMeta
                ObjectMetadata meta = object.getObjectMetadata();
 //Obtain the object's input stream
                InputStream objectContent = object.getObjectContent();
 // Process object
                FileOutputStream fos=new FileOutputStream(android.os.Environment.getExternalStorageDirectory()+"/1/file");  
                byte[] buffer=new byte[<bufferSize>];  
                int count=0;  
                while ((count=objectContent.read(buffer))>=0) {  
                    fos.write(buffer,0,count);  
                }  
                System.out.println(meta.getETag());
                System.out.println(meta.getContentLength());
 // Close stream
                objectContent.close();
                fos.close();
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (IOException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Obtain object via GetObjectRequest

To unlock more capabilities, GetObjectRequest can be used to retrieve objects.

Basic workflow
1. Create an instance of the GetObjectRequest class.
2. Invoke the setRange() method on GetObjectRequest to retrieve specific byte ranges from the object.
3. Execute the client.getObject() operation.

Example code

                Java
                
            

                // Create GetObjectRequest
GetObjectRequest getObjectRequest = new GetObjectRequest(<BucketName>, <ObjectKey>);
 // Obtain data within the 0~100 byte range
getObjectRequest.setRange(0, 100);
 //Obtain the object, with returned result BosObject object
BosObject object = client.getObject(getObjectRequest);
            

Plain Text

1> **Note:** The setRange() method in GetObjectRequest allows users to specify a range for the returned object. This feature can be used to implement segmented downloads and resumable uploads.

Obtain download progress

Users can track download progress via a callback function.

The SDK offers a download progress callback API, which allows you to define necessary operations during the upload process, such as updating the API.

                Java
                
            

                public interface BceProgressCallback<T extends AbstractBceRequest> {
 // request is the download request
 // currentSize is the current download size (unit: byte)
 // totalSize is the total size to be downloaded in this request (unit: byte)
          void onProgress(T request, long currentSize, long totalSize);
    ｝
            

Example code

                Java
                
            

                GetObjectRequest request = new GetObjectRequest()
        .withBucketName(this.bucketName)
        .withKey(objectKey)
        .withRange(0, 5);
request.setProgressCallback(new BosProgressCallback<GetObjectRequest>() {
    @Override
    public void onProgress(GetObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
InputStream input = this.client.getObject(request).getObjectContent();
            

Plain Text

1> **Note:** The download progress interface differs from the upload progress interface. It is not possible to specify the fragment size of the increase in the download volume during each callback.

Download object to a specified path

Users can use the following code to directly download an object to a specified path.

Basic workflow
1. Create an instance of the GetObjectRequest class.
2. Execute the client.getObject() operation.
3. Download an object directly to a specified path.

Example code

                Java
                
                // Create GetObjectRequest
GetObjectRequest getObjectRequest = new GetObjectRequest(<BucketName>, <ObjectKey>);
 // Download object to file
ObjectMetadata objectMetadata = client.getObject(getObjectRequest, new File("/path/to/file","w+"));

Plain Text

1> **Note:** When using the above method to directly download an object to a specified path, the method returns an ObjectMetadata object.

Obtain the storageClass of an object

The storage classes of an object are categorized as STANDARD (standard storage), STANDARD_IA (infrequent access storage), COLD (cold storage), and ARCHIVE (archive storage).

Example code

                Java
                
            

                public void getObjectStorageClass(){
  //...
ObjectMetadata meta = client.getObjectMetadata(bucketName, key);
String storageClass = meta.getStorageClass();
}
            

Obtain only ObjectMetadata

The getObjectMetadata() method retrieves only the ObjectMetadata, without obtaining the object itself.

Example code

                Java
                
                ObjectMetadata objectMetadata = client.getObjectMetadata(<BucketName>, <ObjectKey>);

Get object URL

The following code allows you to get the URL of a specific object, which is commonly used for temporarily sharing the object's URL with others.

Basic workflow
1. Instantiate the BOSClient class.
2. Call the BOSClient.generatePresignedUrl() method.
3. The method returns the URL of the object.

Example code

                Java
                
                URL url = client.generatePresignedUrl(<BucketName>, <ObjectKey>, <ExpirationInSeconds>);

Plain Text

1> **Note:**` ExpirationInSeconds` is the specified URL validity period, calculated from the current time. It is an optional parameter, and the system default value is 1,800 s if not configured. To set a permanent non-expiration time, the `ExpirationInSeconds` parameter can be set to -1. You cannot set it to any other negative value.

Complete example

                Java
                
            

                import java.net.URL;
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 //Obtain the object URL
                URL url = client.generatePresignedUrl(<BucketName>, <ObjectKey>, 2000);  
                Uri uri = Uri.parse(url.toString());
                Intent intent = new Intent(Intent.ACTION_VIEW, uri);
 // Execute URL
                startActivity(intent);
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Object permission control

Set access permission for an object.

Currently, BOS provides two ways to configure ACLs. The first is to use Canned ACL. During PutObjectAcl, object permissions are set through the headers "x-bce-acl" or "x-bce-grant-permission". Available permission options include private and public-read. Note that these two headers cannot be included in the same request. The second method involves uploading an ACL file.

For details, refer to Setting Object Permission Control..

Set object access permission using the headers "x-bce-acl" or "x-bce-grant-permission"

set object acl First method (Set via request headers)

                Java
                
                SetObjectAclRequest setObjectAclRequest = new SetObjectAclRequest("yourBucketName","objectKey",CannedAccessControlList.PublicRead);
client.setObjectAcl(setObjectAclRequest);

set object acl First method (Set xBceGrantRead via request headers)

                Java
                
            

                String xBceGrantRead = "id=\"user_id1\""+",id=\"user_id2\"";
SetObjectAclRequest setObjectAclRequest = new SetObjectAclRequest();
setObjectAclRequest.withBucketName("yourBucketName");
setObjectAclRequest.withKey("objectKey");
setObjectAclRequest.setxBceGrantRead(xBceGrantRead);
client.setObjectAcl(setObjectAclRequest);
            

set object acl First method (Set xBceGrantFullControl via request headers)

                Java
                
            

                String xBceGrantFullControl = "id=\"user_id1\""+",id=\"user_id2\"";
SetObjectAclRequest setObjectAclRequest = new SetObjectAclRequest();
setObjectAclRequest.withBucketName("yourBucketName");
setObjectAclRequest.withKey("objectKey");
setObjectAclRequest.setxBceGrantFullControl(xBceGrantFullControl);
client.setObjectAcl(setObjectAclRequest);
            

Set object access permission via setObjectAcl

set object acl Second Method (JSON string)

                Java
                
                String jsonObjectAcl = "{\"accessControlList\":["+ "{\"grantee\":[{\"id\":\"*\"}], "+ "\"permission\":[\"FULL_CONTROL\"]"+"}]}";
SetObjectAclRequest setObjectAclRequest = new SetObjectAclRequest("yourBucketName","objectKey",jsonObjectAcl);
client.setObjectAcl(setObjectAclRequest);

set object acl Second Method, by which users only need to specify the specified parameters

                Java
                
            

                List<Grant> grants = new ArrayList<Grant>();
List<Grantee> grantees = new ArrayList<Grantee>();
List<Permission> permissions = new ArrayList<Permission>();
 // Grant permission to specific user
grantees.add(new Grantee("user_id1"));
grantees.add(new Grantee("user_id2"));
grantees.add(new Grantee("user_id3"));
 // Set permissions
permissions.add(Permission.READ);
grants.add(new Grant().withGrantee(grantees).withPermission(permissions));
SetObjectAclRequest setObjectAclRequest = new SetObjectAclRequest("yourBucketName","objectKey", grants);
client.setObjectAcl(setObjectAclRequest);
            

View object permissions

The following code can be used to check the object permissions:

                Java
                
                GetObjectAclRequest getObjectRequest = new GetObjectAclRequest();
getObjectRequest.withBucketName("yourBucketName");
getObjectRequest.withKey("objectKey");
GetObjectAclResponse response = client.getObjectAcl(getObjectRequest);

The parameters available for calling in the resolution class returned by the getObjectAcl method are as follows:

Parameters	Description
accessControlList	Identify the permission list of the object
grantee	Identify the grantee
-id	Authorized person ID
permission	Identify the grantee permissions

Delete object permissions

The following code can be used to delete the object permissions:

                Java
                
                DeleteObjectAclRequest deleteObjectAclRequest = new DeleteObjectAclRequest("yourBucketName","objectKey");
client.deleteObjectAcl(deleteObjectAclRequest);

Delete Object

Basic workflow
1. Instantiate the BOSClient class.
2. Invoke the BOSClient.deleteObject() method.
3. If the operation fails, an exception is thrown; if successful, no return value is provided.

Example code

                Java
                
                // Delete Object
 client.deleteObject(＜BucketName＞, ＜ObjectKey＞);   //Specify the name of the bucket where the object to be deleted is located and the name of the object

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Delete Object
 client.deleteObject(<BucketName>, <ObjectKey>);   //Specify the name of the bucket where the object to be deleted is located and the name of the object
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Copy Object

Simply Copy Object

Basic workflow
1. Instantiate the BOSClient class.
2. Call the BOSClient.copyObject() method.
3. The method returns a CopyObjectResponse instance. The eTag and last modification time can be obtained through getETag() and getLastModified().

Example code

                Java
                
                // Copy Object
 CopyObjectResponse copyObjectResponse = client.copyObject(<SrcBucketName>, <SrcKey>, <DestBucketName>, <DestKey>);  //SrcBucketName, SrcKey are the source addresses，DestBucketName, DestKey are the destination addresses to which the copy is made
 // Print results
System.out.println("ETag: " + copyObjectResponse.getETag() + " LastModified: " + copyObjectResponse.getLastModified());

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.CopyObjectResponse;
public class ExampleActivity extends Activity {
private String srcBucketName = <SrcBucketName>;
private String srcKey = <SrcKey>;
private String destBucketName = <DestBucketName>;
private String destKey = <DestKey>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
 // Copy Object
                CopyObjectResponse copyObjectResponse = client.copyObject(<SrcBucketName>, <SrcKey>, <DestBucketName>, <DestKey>);
 // Print results
                System.out.println("ETag: " + copyObjectResponse.getETag() + " LastModified: " + copyObjectResponse.getLastModified());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Plain Text

1> **Note:** The copyObject method returns a `CopyObjectResponse` object containing the new object's ETag and modification time.

Copy Object via CopyObjectRequest

You can also copy object via CopyObjectRequest This function is typically used in the following scenarios:

Copy an object while resetting its metadata.
Reset the metadata of an existing object (set the source and destination to the same object).
Basic workflow
1. Create an instance of the CopyObjectRequest class, and pass in the parameters <SrcBucketName>, <SrcKey>, <DestBucketName>, <DestKey>.
2. Create an ObjectMetadata instance.
3. The method returns a CopyObjectResponse instance. The eTag and last modification time can be obtained through getETag() and getLastModified().

Example code

                Java
                
            

                // Create CopyObjectRequest object
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(<SrcBucketName>, <SrcKey>, <DestBucketName>, <DestKey>);
 // Set new Metadata
Map<String, String> userMetadata = new HashMap<String, String>();
userMetadata.put(<UserMetaKey>,<UserMetaValue>);
meta.setUserMetadata(userMetadata);
copyObjectRequest.setNewObjectMetadata(meta);
 // Copy Object
CopyObjectResponse copyObjectResponse = client.copyObject(copyObjectRequest);
System.out.println("ETag: " + copyObjectResponse.getETag() + " LastModified: " + copyObjectResponse.getLastModified());
            

Plain Text

1> **Note:**` CopyObjectRequest` allows users to modify the ObjectMeta of the target object and also provides the setting of the `MatchingETagConstraints` parameter.

Multipart upload of objects

Multipart Upload Scenarios

In addition to using the putObject() method for file uploads to BOS, BOS also supports another upload mode called Multipart Upload. This mode can be used in scenarios such as:

When resumable uploads are required.
When uploading files larger than 5GB.
When the connection to the BOS server is frequently interrupted due to unstable network conditions.
Enable streaming file uploads.
The file size cannot be determined before uploading.

Multipart Upload Process

Suppose there is a file with the local path /path/to/file.zip. Since the file is large, multipart upload is used to transmit it to BOS.

Basic workflow
1. Start a multipart upload.
2. Upload individual parts.
3. Finalize the multipart upload.

Initialize Multipart Upload

Use initiateMultipartUpload method to initialize a multipart upload event:

Example code

                Java
                
            

                // Initiate Multipart Upload
InitiateMultipartUploadRequest initiateMultipartUploadRequest =
      new InitiateMultipartUploadRequest(<BucketName>, <ObjectKey>);
InitiateMultipartUploadResponse initiateMultipartUploadResponse =
      client.initiateMultipartUpload(initiateMultipartUploadRequest);
 // Print UploadId
System.out.println("UploadId: " + initiateMultipartUploadResponse.getUploadId());
            

Plain Text

1> **Note:** The return result of `initiateMultipartUpload` contains `UploadId`, which is the unique identifier for distinguishing multipart upload events, and we will use it in subsequent operations.

Upload parts

Upload the file in segments.

Example code

                Java
                
            

                // Set each part to 5MB
final long partSize = 1024 * 1024 * 5L;
File partFile = new File("/path/to/file.zip");
 // Calculate the count of parts
int partCount = (int) (partFile.length() / partSize);
if (partFile.length() % partSize != 0) {
    partCount++;
}
 // Create a list to save the ETag and PartNumber of each uploaded part
List<PartETag> partETags = new ArrayList<PartETag>();
 // Get file stream
FileInputStream fis = new FileInputStream(partFile);
for (int i = 0; i < partCount; i++) {
 // Calculate the size of each part
    long skipBytes = partSize * i;
    long size = partSize < partFile.length() - skipBytes ?
              partSize : partFile.length() - skipBytes;
    byte[] buf = new byte[(int)size];
    int offset = 0;
    while (true) {
        int byteRead = fis.read(buf, offset, (int)size);
        offset += byteRead;
        if (byteRead < 0 || offset >= size) {
           break;
        }
    }
    ByteArrayInputStream bufStream = new ByteArrayInputStream(buf);
 // Create UploadPartRequest to upload parts
    UploadPartRequest uploadPartRequest = new UploadPartRequest();
    uploadPartRequest.setBucketName(bucketName);
    uploadPartRequest.setKey(objectkey);
    uploadPartRequest.setUploadId(initiateMultipartUploadResponse.getUploadId());
    uploadPartRequest.setInputStream(bufStream);
    uploadPartRequest.setPartSize(size);
    uploadPartRequest.setPartNumber(i + 1);
 // Upload progress callback
    uploadPartRequest.setProgressCallback(new BosProgressCallback<UploadPartRequest>() {
        @Override
        public void onProgress(UploadPartRequest request, long currentSize, long totalSize) {
            Log.e(currentSize + "", totalSize + "");
        }
    });
    UploadPartResponse uploadPartResponse = client.uploadPart(uploadPartRequest);
 // Save the returned PartETag to the List.
    partETags.add(uploadPartResponse.getPartETag());
    System.out.println(uploadPartResponse.getPartETag());
  }
 // Close the file
  fis.close();
            

Plain Text

1> **Note:** The core of the above code is to call the `UploadPart` method to upload each part concurrently, but the following points should be noted:
2>
3> -   The UploadPart method requires the size of each part to either be an integer multiple of 1MB or greater than 5MB. However, the Upload Part interface does not validate the part size immediately; this check happens only during the finalization of the multipart upload.  
4> -   To ensure no errors during network transmission, it is recommended to use the Content-MD5 value returned by BOS for each part after `UploadPart` to verify the correctness of the uploaded part data. When all part data is combined into one Object, it no longer contains the MD5 value.
5> -   The part number must be within the range of 1 to 10,000. If this limit is exceeded, BOS will return an InvalidArgument error code.  
6> -   For each uploaded part, the stream must be positioned at the beginning of the respective part.  
7> -   After each Part upload, the return result of BOS will include a `PartETag` object, which is a combination of the uploaded block's ETag and block number (PartNumber). It will be used in subsequent steps to complete the multipart upload, so it must be saved. Generally speaking, these `PartETag` objects will be saved in a List.
8> -   For details on using the progress callback API, refer to the chapter titled "Obtain Upload Progress."

Complete multipart upload

Example code

                Java
                
            

                CompleteMultipartUploadRequest completeMultipartUploadRequest =
      new CompleteMultipartUploadRequest(<BucketName>, <ObjectKey>,
            initiateMultipartUploadResponse.getUploadId(), partETags);
 // Complete multipart upload
CompleteMultipartUploadResponse completeMultipartUploadResponse =
      client.completeMultipartUpload(completeMultipartUploadRequest);
 // Print Object's ETag
System.out.println(completeMultipartUploadResponse.getETag());
            

Plain Text

1> **Note:** The `partETags` in the above code is the list of partETag saved in the second step. After BOS receives the Part list submitted by the user, it will verify the validity of each data Part one by one. Once all data parts are validated, BOS will assemble the data parts into a complete Object.

Complete example

                Java
                
            

                import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import org.json.JSONException;
import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.CompleteMultipartUploadRequest;
import com.baidubce.services.bos.model.CompleteMultipartUploadResponse;
import com.baidubce.services.bos.model.InitiateMultipartUploadRequest;
import com.baidubce.services.bos.model.InitiateMultipartUploadResponse;
import com.baidubce.services.bos.model.PartETag;
import com.baidubce.services.bos.model.UploadPartRequest;
import com.baidubce.services.bos.model.UploadPartResponse;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
​    
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
              BosClientConfiguration config = new BosClientConfiguration();
              config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
              config.setEndpoint(<EndPoint>);
              BosClient client = new BosClient(config);
 // Initiate Multipart Upload
              InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(<BucketName>, <ObjectKey>);
              InitiateMultipartUploadResponse initiateMultipartUploadResponse =
                        client.initiateMultipartUpload(initiateMultipartUploadRequest);
 // Print UploadId
              System.out.println("UploadId: " + initiateMultipartUploadResponse.getUploadId());
 // Set each part to 5MB
              final long partSize = 1024 * 1024 * 5L;
              File partFile = new File("/path/to/file.zip");
 // Calculate the count of parts
              int partCount = (int) (partFile.length() / partSize);
              if (partFile.length() % partSize != 0) {
                  partCount++;
              }
 // Create a list to save the ETag and PartNumber of each uploaded part
              List<PartETag> partETags = new ArrayList<PartETag>();
 // Get file stream
              FileInputStream fis = new FileInputStream(partFile);
              for (int i = 0; i < partCount; i++) {                       
 // Calculate the size of each part
                  long skipBytes = partSize * i;
                  long size = partSize < partFile.length() - skipBytes ?
                          partSize : partFile.length() - skipBytes;
                  byte[] buf = new byte[(int)size];
                  int offset = 0;
                  while (true) {
                      int byteRead = fis.read(buf, offset, (int)size);
                      offset += byteRead;
                      if (byteRead < 0 || offset >= size) {
                          break;
                      }
                  }
                  ByteArrayInputStream bufStream = new ByteArrayInputStream(buf);
 // Create UploadPartRequest to upload parts
                  UploadPartRequest uploadPartRequest = new UploadPartRequest();
                  uploadPartRequest.setBucketName(<BucketName>);
                  uploadPartRequest.setKey(<ObjectKey>);
                  uploadPartRequest.setUploadId(initiateMultipartUploadResponse.getUploadId());
                  uploadPartRequest.setInputStream(fis);
                  uploadPartRequest.setPartSize(size);
                  uploadPartRequest.setPartNumber(i + 1);
                  UploadPartResponse uploadPartResponse = client.uploadPart(uploadPartRequest);
 // Save the returned PartETag to the List.
                  partETags.add(uploadPartResponse.getPartETag());
                  System.out.println(uploadPartResponse.getPartETag());                                         
              }
 // Close the file
              fis.close();
              CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(<BucketName>, <ObjectKey>, initiateMultipartUploadResponse.getUploadId(), partETags);
 // Complete multipart upload
              CompleteMultipartUploadResponse completeMultipartUploadResponse =
                      client.completeMultipartUpload(completeMultipartUploadRequest);
 // Print Object's ETag
              System.out.println(completeMultipartUploadResponse.getETag());
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error Message: " + e.getMessage());
                System.out.println("Error ErrorType: " + e.getErrorType());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            } catch (IOException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            } catch (JSONException e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        }
    }).start();
}}
            

Cancel multipart upload

Users can cancel multipart uploads by using the abortMultipartUpload method.

Example code

                Java
                
                AbortMultipartUploadRequest abortMultipartUploadRequest =
    new AbortMultipartUploadRequest(<BucketName>, <ObjectKey>, <UploadId>);
 // Cancel multipart upload
client.abortMultipartUpload(abortMultipartUploadRequest);

Retrieve unfinished multipart uploads

Users can obtain the unfinished multipart upload events in the bucket by the listMultipartUploads method.

Basic workflow
1. Create an instance of the listMultipartUploadsRequest class, and pass in the parameter <BucketName>.
2. Create a BOSClient instance and invoke the BOSClient.listMultipartUploads() method.
3. The listMultipartUploads() method provides details about all uploaded parts.

Example code

                Java
                
            

                ListMultipartUploadsRequest listMultipartUploadsRequest =
    new ListMultipartUploadsRequest(<BucketName>);
 // Retrieve all upload events within the bucket
ListMultipartUploadsResponse list = client.listMultipartUploads(listMultipartUploadsRequest);
​    
 // Traverse all upload events
for (MultipartUploadSummary multipartUpload : list.getMultipartUploads()) {
    System.out.println("Key: " + multipartUpload.getKey() + " UploadId: " + multipartUpload.getUploadId());
}
            

Plain Text

1> **Note:**
2>
3> -   By default, if the number of multipart upload events in a bucket surpasses 1,000, only 1,000 records will be returned. In such cases, the IsTruncated value in the response will be True, and the NextKeyMarker will indicate the starting point for the next query.  
4> -   To fetch more multipart upload events, use the KeyMarker parameter to retrieve data in batches.

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ListMultipartUploadsRequest;
import com.baidubce.services.bos.model.ListMultipartUploadsResponse;
import com.baidubce.services.bos.model.MultipartUploadSummary;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
                ListMultipartUploadsRequest listMultipartUploadsRequest =
                        new ListMultipartUploadsRequest(<BucketName>);
 // Retrieve all upload events within the bucket
                ListMultipartUploadsResponse listing = client.listMultipartUploads(listMultipartUploadsRequest);
 // Traverse all upload events
                 for (MultipartUploadSummary multipartUpload : listing.getMultipartUploads()) {
                     System.out.println("Key: " + multipartUpload.getKey() + " UploadId: " + multipartUpload.getUploadId());
                 }
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error ErrorType: " + e.getErrorType());
                System.out.println("Error Message: " + e.getMessage());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Get all uploaded part information

Users can obtain all uploaded parts in an upload event by the listParts method.

Basic workflow
1. Create an instance of the ListPartsRequest class, and pass in the parameters <BucketName>, <ObjectKey> and <UploadId>
2. Create a BOSClient instance and invoke the BOSClient.listParts() method.
3. The listParts() method provides details about all uploaded parts.

Example code

                Java
                
            

                ListPartsRequest listPartsRequest = new ListPartsRequest(<BucketName>, <ObjectKey>, <UploadId>);
​    
 // Retrieve all uploaded part information
ListPartsResponse partListing = client.listParts(listPartsRequest);
​    
 // Traverse all parts
for (PartSummary part : partListing.getParts()) {
    System.out.println("PartNumber: " + part.getPartNumber() + " ETag: " + part.getETag());
}
            

Plain Text

1> **Note:**
2>
3> -   By default, if the number of multipart upload events in a bucket surpasses 1,000, only 1,000 records will be returned. In such cases, the IsTruncated value in the response will be True, and the NextPartNumberMarker will indicate the starting point for the next query.  
4> -   To retrieve more information about uploaded parts, use the PartNumberMarker parameter to fetch data in batches.

Complete example

                Java
                
            

                import android.app.Activity;
import android.os.Bundle;
import com.baidubce.BceClientException;
import com.baidubce.BceServiceException;
import com.baidubce.auth.DefaultBceCredentials;
import com.baidubce.demo.R;
import com.baidubce.services.bos.BosClient;
import com.baidubce.services.bos.BosClientConfiguration;
import com.baidubce.services.bos.model.ListPartsRequest;
import com.baidubce.services.bos.model.ListPartsResponse;
import com.baidubce.services.bos.model.PartSummary;
public class ExampleActivity extends Activity {
private String bucketName = <BucketName>;
private String objectKey = <ObjectKey>;
private String uploadId = <UploadId>;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                BosClientConfiguration config = new BosClientConfiguration();
                config.setCredentials(new DefaultBceCredentials(<AccessKeyID>, <SecretAccessKey>));
                config.setEndpoint(<EndPoint>);
                BosClient client = new BosClient(config);
                ListPartsRequest listPartsRequest = new ListPartsRequest(<BucketName>, <ObjectKey>, <UploadId>);
                listPartsRequest.setMaxParts(100);
                listPartsRequest.setPartNumberMarker(50);
 // Retrieve all uploaded part information
                 ListPartsResponse partListing = client.listParts(listPartsRequest);
 // Traverse all parts
                 for (PartSummary part : partListing.getParts()) {
                     System.out.println("PartNumber: " + part.getPartNumber() + " ETag: " + part.getETag());
                 }
            } catch (BceServiceException e) {
                System.out.println("Error ErrorCode: " + e.getErrorCode());
                System.out.println("Error RequestId: " + e.getRequestId());
                System.out.println("Error StatusCode: " + e.getStatusCode());
                System.out.println("Error ErrorType: " + e.getErrorType());
                System.out.println("Error Message: " + e.getMessage());
            } catch (BceClientException e) {
                System.out.println("Error Message: " + e.getMessage());
            }
        }
    }).start();
}}
            

Encapsulate multipart upload

In the Android SDK, BOS provides the putSuperObjectFromFile interface, which consolidates the three main methods for multipart uploads: initiateMultipartUpload, UploadPart, and completeMultipartUpload. Using this interface, users can complete a multipart upload with built-in support for progress synchronization callbacks.

Simple example:

                Java
                
                File file = new File("/path/to/file.zip");
PutSuperObjectRequest request = new PutSuperObjectRequest(bucketName, objectKey, file);
bosClient.putSuperObjectFromFile(request);

Example: Set the part size to 2MB, the thread count to 4, and synchronize progress callbacks every 1,024 bytes

                Java
                
            

                BosClientConfiguration config=new BosClientConfiguration();
config.setUploadSegmentPart(1024);
File file = new File("/path/to/file.zip");
PutSuperObjectRequest request = new PutSuperObjectRequest(bucketName, objectKey,
                                                          file, 1024 * 1024 * 2L, 4);
request.setProgressCallback(new BosProgressCallback<PutSuperObjectRequest>() {
    @Override
    public void onProgress(PutSuperObjectRequest request, long currentSize, long totalSize) {
        Log.e(currentSize + "", totalSize + "");
    }
});
bosClient.putSuperObjectFromFile(request);
            

Note:

By default, the part size is 5MB, the thread count is 5, and the progress callback period is every 2,048 bytes.

If a large file takes a long time to upload and the user wants to end the multipart upload, they can call the cancel() method in PutSuperObjectRequest.

Log

Bucket management