Performing an Asynchronous Resumable Upload

request

UploadFileRequest

Yes

Explanation:

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

completeCallback

TaskCallback

<CompleteMultipartUploadResult, UploadFileRequest>

Yes

Explanation:

Callbacks executed to obtain results (success or exception) for an asynchronous upload.

bucketName

String

Yes

Explanation:

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 a period (.) and a hyphen (-) 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

objectKey

String

Yes

Explanation:

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 can contain 1 to 1,024 characters.

Default value:

None

objectMetadata

ObjectMetadata

No

Explanation:

Object metadata. For details, see Table 4.

Default value:

None

acl

AccessControlList

No

Explanation:

An ACL that can be specified at bucket creation. You can use either a pre-defined or a user-defined ACL. For more information about ACLs, see ACLs.

Value range:

• To use a pre-defined ACL, see Table 5 for the available options.
• To use a user-defined ACL, see Table 6 to configure the required parameters.

Default value:

AccessControlList.REST_CANNED_PRIVATE

sseKmsHeader

SseKmsHeader

No

Explanation:

Server-side encryption header. For details, see Table 7.

Default value:

None

sseCHeader

SseCHeader

No

Explanation:

Server-side encryption header. For details, see Table 8.

Default value:

None

enableCheckpoint

boolean

No

Explanation:

Whether to enable the resumable mode.

Value range:

true: The resumable mode is enabled.

false: The resumable mode is disabled.

Default value:

false

checkpointFile

String

No

Explanation:

Path of a file generated for recording the progress of a resumable upload. The file contains the information about parts and progress.

Restrictions:

This parameter is valid only for resumable uploads.

Default value:

If this parameter is left blank, the progress file will be in the same directory as the local file to be uploaded.

uploadFile

String

Yes

Explanation:

Full path of the file or folder to be uploaded, for example, aa/bb.txt or aa/.

Default value:

None

extensionPermissionMap

Map<ExtensionObjectPermissionEnum, Set<String>>

No

Explanation:

A permission map for granting bucket ACL permissions to one or more accounts. Table 9 specifies the permissions to grant, and Set<String> describes the list of account IDs (indicated by domain_id) the granted permissions apply to.

Value range:

• For details about the available permissions, see Table 9.
• To obtain an account ID, see How Do I Get My Account ID and User ID?

Default value:

None

progressListener

ProgressListener

No

Explanation:

Data transmission listener, used for obtaining the upload progress. For details, see Table 10.

partSize

long

No

Explanation:

Part size.

Value range:

The value ranges from 100 KB to 5 GB, in bytes.

Default value:

9 MB

taskNum

int

No

Explanation:

Maximum number of files that can be uploaded concurrently in a multipart upload.

Value range:

An integer from 1 to 10000

Default value:

1, indicating concurrent uploads are not used.

encodeHeaders

boolean

No

Explanation:

Whether to enable OBS to automatically encode request headers.

Due to HTTP coding restrictions, non-ASCII characters cannot be sent. The SDK encodes the CJK characters in the header field using a URL and then sends the encoded data. For example, if content-disposition is set to attachment; filename="CJK characters.txt", the information stored in the object metadata is attachment; filename="%E4%B8%AD%E6%96%87.txt". When you use a browser to access the object metadata, the browser automatically decodes the data.

Value range:

true: Encoding with SDK is enabled.

false: Encoding with SDK is disabled.

Default value:

true

needCalculateCRC64

boolean

No

Explanation:

Whether to automatically calculate the CRC64 value of the data to be uploaded and submit the CRC64 value to the server for verification.

Restrictions:

This parameter is not supported for POSIX or SFS objects.

Value range:

true: The SDK calculates CRC64 and submits it to the server for verification.

false: CRC64 is not calculated.

Default value:

false

onSuccess

void

result (generic)

Called if the request is completed successfully.

onException

void

ObsException, request (generic)

Called if the request failed. The exception and corresponding request information are returned.

contentLength

Long

No

Explanation:

Object size.

Restrictions:

• The object size in a single upload ranges from 0 to 5 GB.
• To upload files larger than 5 GB, multipart uploads should be used.

Default value:

If this parameter is not specified, the SDK automatically calculates the size of the object.

contentType

String

No

Explanation:

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

Value range:

For details about common content types (MIME), see What Is Content-Type (MIME)?

Default value:

If this parameter is not specified, the SDK determines the file type based on the suffix of the object name and assigns a value to the parameter. For example, if the suffix of the object name is .xml, the object is an application/xml file. If the suffix is .html, the object is a text/html file.

contentEncoding

String

No

Explanation:

Content-Encoding header in the response. It specifies which encoding format is applied to the object.

Default value:

None

contentDisposition

String

No

Explanation:

Provides a default file name for the requested object. When the object with the default file name is being downloaded or accessed, the content is displayed as part of a web page in the browser or as an attachment in a download dialog box.

Default value:

None

cacheControl

String

No

Explanation:

Cache-Control header in the response. It specifies the cache behavior of the web page when an object is downloaded.

Default value:

None

contentLanguage

String

No

Explanation:

Language or language combination for visitors to customize and use. For details, see the definition of ContentLanguage in the HTTP protocol.

Default value:

None

expires

String

No

Explanation:

The time a cached web page object expires.

Restrictions:

The time must be in the GMT format.

Default value:

None

storageClass

StorageClassEnum

No

Explanation:

Storage class of an object that can be specified at object creation. If you do not specify this header, the object inherits the storage class of the bucket.

Value range:

See Table 11.

Default value:

None

webSiteRedirectLocation

String

No

Explanation:

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL. This parameter specifies the address the request for the object is redirected to.

To another object in the same bucket:

WebsiteRedirectLocation:/anotherPage.html

To an external URL:

WebsiteRedirectLocation:http://www.example.com/

Restrictions:

• The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
• OBS only supports redirection for objects in the root directory of a bucket.

Default value:

None

nextPosition

long

No

Explanation:

Start position for the next append upload.

Value range:

0 to the object length, in bytes.

Default value:

None

appendable

boolean

No

Explanation:

Whether the object is appendable.

Value range:

true: The object is appendable.

false: The object is not appendable.

Default value:

None

userMetadata

Map<String, Object>

No

Explanation:

User-defined metadata of the object. To define it, you can add a header starting with x-obs-meta- in the request. In Map, the String key indicates the name of the user-defined metadata that starts with x-obs-meta-, and the Object value indicates the value of the user-defined metadata. To obtain the user-defined metadata of an object, use ObsClient.getObjectMetadata. For details, see Obtaining Customized Metadata.

Restrictions:

• An object can have multiple pieces of metadata. The size of the metadata cannot exceed 8 KB in total.
• When you call ObsClient.getObject to download an object, its user-defined metadata will also be downloaded.

Default value:

None

isTaskFinished

boolean

None

Whether the task is finished.

waitUntilFinished

void

None

Blocks the current thread and waits until the asynchronous upload completes.

cancel

boolean

None

Cancels an asynchronous upload. If the upload was successfully canceled, true is returned; otherwise, false is returned.

getResult

java.util.Optional

<CompleteMultipartUploadResult>

None

Blocks the current thread and waits until the asynchronous upload completes before returning the result. If the upload failed, the value of Optional.isPresent() is false.

statusCode

int

Explanation:

HTTP status code.

Value range:

A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors).

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

bucketName

String

Explanation:

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 a period (.) and a hyphen (-) 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

objectKey

String

Explanation:

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 can contain 1 to 1,024 characters.

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

versionId

String

Explanation:

Object version ID. If versioning is enabled for the bucket, the object version ID will be returned.

Value range:

The value must contain 32 characters.

Default value:

None