Help Center/ Object Storage Service/ SDK Reference/ Java/ Object Management (SDK for Java)/ Copying an Object - Multipart (SDK for Java)
Updated on 2024-06-18 GMT+08:00

Copying an Object - Multipart (SDK for Java)

Function

This API allows you to upload a part by copying an object or part of this object.

You can call ObsClient.copyPart to copy parts.

If you have any questions during development, post them on the Issues page of GitHub.

Restrictions

  • To copy an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
  • You must have the read permission on the source object.
  • The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
  • The object copy request carries the information about the source bucket and object to be copied in the header field. The message body cannot be carried.
  • Cross-bucket replication in the same region is supported, but cross-region replication is not supported.
  • If the source object is in the Archive storage class, you must restore it first.

Method

obsClient.copyPart(CopyPartRequest request)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

request

CopyPartRequest

Yes

Explanation:

Request parameters for copying an object. For details, see Table 2.

Table 2 CopyPartRequest

Parameter

Type

Mandatory (Yes/No)

Description

sourceBucketName

String

Yes

Explanation:

Name of the source bucket.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

sourceObjectKey

String

Yes

Explanation:

Source object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

destinationBucketName

String

Yes

Explanation:

Target bucket name.

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

destinationObjectKey

String

Yes

Explanation:

Target object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

byteRangeStart

Long

No

Explanation:

Start position for the multipart copy

Value range:

A non-negative integer, in bytes.

Default value:

0

byteRangeEnd

Long

No

Explanation:

End position for the multipart copy

Restrictions:

The value must be greater than that of RangeStart. The upper limit of the value is the object length minus 1, in bytes.

Value range:

A non-negative integer, in bytes.

Default value:

None

sseCHeaderSource

SseCHeader

No

Explanation:

Server-side header used for decrypting the source object. For details, see Table 3.

sseCHeaderDestination

SseCHeader

No

Explanation:

Server-side encryption header used for encrypting the target object. For details, see Table 3.

Restrictions:

If the object uploaded to a server is encrypted with the key provided by the client, the key must also be provided in the message for downloading the object.

versionId

String

No

Explanation:

Version ID of the source object, for example, G001117FCE89978B0000401205D5DC9A. If the source object has multiple versions, you can specify this parameter.

Value range:

The value must contain 32 characters.

Default value:

None

partNumber

int

Yes

Explanation:

Part number.

Value range:

An integer ranging from 1 to 10000

Default value:

None

uploadId

String

Yes

Explanation:

Multipart upload ID, for example, 000001648453845DBB78F2340DD460D8.

Value range:

The value must contain 32 characters.

Default value:

None

Table 3 SseCHeader

Parameter

Type

Mandatory (Yes/No)

Description

algorithm

ServerAlgorithm

Yes

Explanation:

SSE-C is used for encrypting objects on the server side.

Value range:

AES256, indicating AES is used to encrypt the object in SSE-C. For details, see Table 4.

Default value:

None

sseAlgorithm

SSEAlgorithmEnum

No

Explanation:

Encryption algorithm.

Restrictions:

Only AES256 is supported.

Value range:

See Table 5.

Default value:

None

sseCKey

byte[]

Yes

Explanation:

Key used for encrypting the object when SSE-C is used, in byte[] format.

Default value:

None

sseCKeyBase64

String

No

Explanation:

Base64-encoded key used for encrypting the object when SSE-C is used.

Default value:

None

Table 4 ServerAlgorithm

Constant

Default Value

AES256

AES256

Table 5 SSEAlgorithmEnum

Constant

Default Value

KMS

kms

AES256

AES256

Responses

Table 6 CopyPartResult

Parameter

Type

Description

statusCode

int

Explanation:

HTTP status code.

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response.

For more information, see Status Code.

Default value:

None

responseHeaders

Map<String, Object>

Explanation:

Response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header.

Default value:

None

partNumber

int

Explanation:

Part number.

Value range:

An integer ranging from 1 to 10000.

Default value:

None

etag

String

Explanation:

ETag of an object, which is a Base64-encoded 128-bit MD5 digest. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, the object content is changed. The ETag reflects changes only to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

Restrictions:

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

Value range:

The value must contain 32 characters.

Default value:

None

lastModified

java.util.Date

Explanation:

Last time the target part was modified.

Default value:

None

Code Examples

This example copies object sourceobjectname in parts from bucket sourcebucketname to bucket destbucketname as object destobjectname.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.CompleteMultipartUploadRequest;
import com.obs.services.model.CopyPartRequest;
import com.obs.services.model.CopyPartResult;
import com.obs.services.model.InitiateMultipartUploadRequest;
import com.obs.services.model.InitiateMultipartUploadResult;
import com.obs.services.model.ObjectMetadata;
import com.obs.services.model.PartEtag;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
public class CopyPart001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
        String endPoint = "https://obs.ap-southeast-1.myhuaweicloud.com";
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        
        // Create an ObsClient instance.
        // Use the permanent AK/SK pair to initialize the client.
        ObsClient obsClient = new ObsClient(ak, sk,endPoint);
        // Use the temporary AK/SK pair and security token to initialize the client.
        // ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint);

        try {
            // Copy parts.
            final String destBucketName = "destbucketname";
            final String destObjectKey = "destobjectname";
            final String sourceBucketName = "sourcebucketname";
            final String sourceObjectKey = "sourceobjectname";
            // Initialize the thread pool.
            ExecutorService executorService = Executors.newFixedThreadPool(20);
            // Initiate a multipart upload.
            InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(destBucketName, destObjectKey);
            InitiateMultipartUploadResult result = obsClient.initiateMultipartUpload(request);
            final String uploadId = result.getUploadId();
            System.out.println("uploadId:" + uploadId + "\n");
            // Obtain information about the large object.
            ObjectMetadata metadata = obsClient.getObjectMetadata(sourceBucketName, sourceObjectKey);
            // Set the part size to 100 MB.
            long partSize = 100 * 1024 * 1024L;
            long objectSize = metadata.getContentLength();
            // Calculate the number of parts to be copied.
            long partCount = objectSize % partSize == 0 ? objectSize / partSize : objectSize / partSize + 1;
            final List<PartEtag> partEtags = Collections.synchronizedList(new ArrayList<>());
            // Start copying parts concurrently.
            for (int i = 0; i < partCount; i++) {
                // Start position for copying parts
                final long rangeStart = i * partSize;
                // End position for copying parts
                final long rangeEnd = (i + 1 == partCount) ? objectSize - 1 : rangeStart + partSize - 1;
                // Set the part number.
                final int partNumber = i + 1;
                executorService.execute(
                        new Runnable() {
                            @Override
                            public void run() {
                                CopyPartRequest request = new CopyPartRequest();
                                request.setUploadId(uploadId);
                                request.setSourceBucketName(sourceBucketName);
                                request.setSourceObjectKey(sourceObjectKey);
                                request.setDestinationBucketName(destBucketName);
                                request.setDestinationObjectKey(destObjectKey);
                                request.setByteRangeStart(rangeStart);
                                request.setByteRangeEnd(rangeEnd);
                                request.setPartNumber(partNumber);
                                CopyPartResult result;
                                try {
                                    result = obsClient.copyPart(request);
                                    System.out.println("Part#" + partNumber + " done\n");
                                    partEtags.add(new PartEtag(result.getEtag(), result.getPartNumber()));
                                } catch (ObsException e) {
                                    e.printStackTrace();
                                }
                            }
                        });
            }
            // Wait until the copy is complete.
            executorService.shutdown();
            while (!executorService.isTerminated()) {
                try {
                    executorService.awaitTermination(5, TimeUnit.SECONDS);
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
            }
            // Assemble parts.
            CompleteMultipartUploadRequest completeMultipartUploadRequest =
                    new CompleteMultipartUploadRequest(destBucketName, destObjectKey, uploadId, partEtags);
            obsClient.completeMultipartUpload(completeMultipartUploadRequest);
            System.out.println("copyObject successfully");
        } catch (ObsException e) {
            System.out.println("copyObject failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code:" + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message:" + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
            e.printStackTrace();
        } catch (Exception e) {
            System.out.println("copyObject failed");
            // Print other error information.
            e.printStackTrace();
        }
    }
}