Object Storage Service:Append upload (Java SDK V1)

Notes

• In this topic, the public endpoint of the China (Hangzhou) region is used. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For details about supported regions and endpoints, see Regions and endpoints.

• In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.

• In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Configuration examples for common scenarios.

• If the file does not exist, a call to the AppendObject API operation creates an appendable object.

• If the file already exists:

  • If the file is an appendable object and the specified append position is the same as the current length of the file, the content is appended to the end of the file.

  • If the file is an appendable object but the specified append position is not the same as the current length of the file, a PositionNotEqualToLength exception is thrown.

  • If the file is not an appendable object, such as a Normal object that was uploaded using a simple upload, an ObjectNotAppendable exception is thrown.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket policies.

Sample code

The following code provides an example of how to append data to an object.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AppendObjectRequest;
import com.aliyun.oss.model.AppendObjectResult;
import com.aliyun.oss.model.ObjectMetadata;
import java.io.ByteArrayInputStream;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Set the Endpoint. China (Hangzhou) is used as an example. Set the value as needed.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name. Example: examplebucket.
        String bucketName = "examplebucket";
        // Specify the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt.
        String objectName = "exampledir/exampleobject.txt";
        String content1 = "Hello OSS A \n";
        String content2 = "Hello OSS B \n";
        String content3 = "Hello OSS C \n";
        // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSSClient instance.
        // After the OSSClient instance is no longer used, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            ObjectMetadata meta = new ObjectMetadata();
            // Specify the content type.
            meta.setContentType("text/plain");
            // Specify the web page caching behavior of the object.
            //meta.setCacheControl("no-cache");
            // Specify the name of the object when it is downloaded.
            //meta.setContentDisposition("attachment;filename=oss_download.txt");
            // Specify the content encoding format of the object.
            //meta.setContentEncoding(OSSConstants.DEFAULT_CHARSET_NAME);
            // This request header is used to check whether the message content is consistent with the content sent.
            //meta.setContentMD5("ohhnqLBJFiKkPSBO1eNaUA==");
            // Specify the expiration time.
            //try {
            //    meta.setExpirationTime(DateUtil.parseRfc822Date("Wed, 08 Jul 2022 16:57:01 GMT"));
            //} catch (ParseException e) {
            //    e.printStackTrace();
            //}
            // Specify the server-side encryption method. In this example, server-side encryption with OSS-managed keys (SSE-OSS) is used.
            //meta.setServerSideEncryption(ObjectMetadata.AES_256_SERVER_SIDE_ENCRYPTION);
            // Specify the access permissions of the object. In this example, the access permissions are set to private.
            //meta.setObjectAcl(CannedAccessControlList.Private);
            // Specify the storage class of the object.
            //meta.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);
            // You can add x-oss-meta-* when you create an appendable object. You cannot carry this parameter for subsequent appends. If you configure a parameter prefixed with x-oss-meta-*, the parameter is considered metadata.
            //meta.setHeader("x-oss-meta-author", "Alice");

            // Set multiple parameters using AppendObjectRequest.
            AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(content1.getBytes()),meta);

            // Set a single parameter using AppendObjectRequest.
            // Set the bucket name.
            //appendObjectRequest.setBucketName(bucketName);
            // Set the object name.
            //appendObjectRequest.setKey(objectName);
            // Set the content to be appended. The content can be of the InputStream or File type. In this example, the content is of the InputStream type.
            //appendObjectRequest.setInputStream(new ByteArrayInputStream(content1.getBytes()));
            // Set the content to be appended. The content can be of the InputStream or File type. In this example, the content is of the File type.
            //appendObjectRequest.setFile(new File("D:\\localpath\\examplefile.txt"));
            // Specify the metadata of the file. This is valid only for the first append.
            //appendObjectRequest.setMetadata(meta);

            // First append.
            // Set the append position of the file.
            appendObjectRequest.setPosition(0L);
            AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
            // The 64-bit CRC value of the file.
            System.out.println(appendObjectResult.getObjectCRC());

            // Second append.
            // nextPosition indicates the position that should be provided in the next request, which is the current length of the file.
            appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
            appendObjectRequest.setInputStream(new ByteArrayInputStream(content2.getBytes()));
            appendObjectResult = ossClient.appendObject(appendObjectRequest);

            // Third append.
            appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
            appendObjectRequest.setInputStream(new ByteArrayInputStream(content3.getBytes()));
            appendObjectResult = ossClient.appendObject(appendObjectRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

References

• For the complete sample code for an append upload, see GitHub sample.

• For more information about the API operation for an append upload, see AppendObject.