Object Manage

The WOS Java SDK provides comprehensive object management interfaces. This article introduces common operations for managing objects using these interfaces.

1. Set Object Metadata

You can set object metadata, including custom user metadata, using WosClient.setObjectMetadata. The example below demonstrates how to set object metadata:

String endPoint = "https://your-endpoint";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

// Create WosClient instance
final WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

SetObjectMetadataRequest request = new SetObjectMetadataRequest("bucketname", "objectname");
request.addUserMetadata("property1", "property-value1");
// Set custom metadata
ObjectMetadata metadata = wosClient.setObjectMetadata(request);

System.out.println("\t" + metadata.getUserMetadata("property1"));

2. Get Object Metadata

You can retrieve object metadata, including object size, MIME type, and custom user metadata, using WosClient.getObjectMetadata. The following example shows how to get object metadata:

String endPoint = "https://your-endpoint";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

// Create WosClient instance
final WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

ObjectMetadata metadata = wosClient.getObjectMetadata("bucketname", "objectname");
System.out.println("\t" + metadata.getContentType());
System.out.println("\t" + metadata.getContentLength());
System.out.println("\t" + metadata.getUserMetadata("property"));

3. Get Object ACL

You can retrieve the object’s access control list (ACL) using WosClient.getObjectAcl. The following example shows how to get an object’s ACL:

String endPoint = "https://your-endpoint";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

// Create WosClient instance
final WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

AccessControlList acl = wosClient.getObjectAcl("bucketname", "objectname");
System.out.println(acl);

4. List Objects

You can list the objects in a bucket using WosClient.listObjects.

Configurable Parameters

Simple Listing

The example below lists objects, with up to 1,000 results per request:

String endPoint = "https://your-endpoint";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

// Create WosClient instance
final WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

ObjectListing result = wosClient.listObjects("bucketname");
for (WosObject wosObject : result.getObjects()) {
    System.out.println("\t" + wosObject.getObjectKey());
    System.out.println("\t" + wosObject.getOwner());
}

Notes:

• Each call returns a maximum of 1,000 objects. If there are more than 1,000, ObjectListing.isTruncated is true. Use ObjectListing.getNextMarker for subsequent paginated requests.
• Use paginated listing to retrieve all objects.

Listing a Specific Number of Objects

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setMaxKeys(100);
ObjectListing result = wosClient.listObjects(request);
for (WosObject wosObject : result.getObjects()) {
    System.out.println("\t" + wosObject.getObjectKey());
    System.out.println("\t" + wosObject.getOwner());
}

Listing Objects with a Prefix

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setMaxKeys(100);
request.setPrefix("prefix");
ObjectListing result = wosClient.listObjects(request);
for (WosObject wosObject : result.getObjects()) {
    System.out.println("\t" + wosObject.getObjectKey());
    System.out.println("\t" + wosObject.getOwner());
}

Listing Objects from a Marker

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setMaxKeys(100);
request.setMarker("test");
ObjectListing result = wosClient.listObjects(request);
for (WosObject wosObject : result.getObjects()) {
    System.out.println("\t" + wosObject.getObjectKey());
    System.out.println("\t" + wosObject.getOwner());
}

Paginated Listing of All Objects

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setMaxKeys(100);

ObjectListing result;
do {
    result = wosClient.listObjects(request);
    for (WosObject wosObject : result.getObjects()) {
        System.out.println("\t" + wosObject.getObjectKey());
        System.out.println("\t" + wosObject.getOwner());
    }
    request.setMarker(result.getNextMarker());
} while (result.isTruncated());

List All Objects Within a “Folder”

WOS does not support folders natively; objects are stored directly in the bucket. A folder is simulated by a zero-size object whose key ends with “/”. To list objects as if in a folder, specify the folder prefix:

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setPrefix("dir/");
request.setMaxKeys(1000);

ObjectListing result;
do {
    result = wosClient.listObjects(request);
    for (WosObject wosObject : result.getObjects()) {
        System.out.println("\t" + wosObject.getObjectKey());
        System.out.println("\t" + wosObject.getOwner());
    }
    request.setMarker(result.getNextMarker());
} while (result.isTruncated());

List All Objects by Folder (Group by Directory)

ListObjectsRequest request = new ListObjectsRequest("bucketname");
request.setMaxKeys(1000);
// Set delimiter to "/"
request.setDelimiter("/");
ObjectListing result = wosClient.listObjects(request);
System.out.println("Objects in the root directory:");
for (WosObject wosObject : result.getObjects()) {
    System.out.println("\t" + wosObject.getObjectKey());
    System.out.println("\t" + wosObject.getOwner());
}
listObjectsByPrefix(wosClient, request, result);

static void listObjectsByPrefix(WosClient wosClient, ListObjectsRequest request, ObjectListing result) throws WosException {
    for (String prefix : result.getCommonPrefixes()) {
        System.out.println("Objects in folder [" + prefix + "]:");
        request.setPrefix(prefix);
        result = wosClient.listObjects(request);
        for (WosObject wosObject : result.getObjects()) {
            System.out.println("\t" + wosObject.getObjectKey());
            System.out.println("\t" + wosObject.getOwner());
        }
        listObjectsByPrefix(wosClient, request, result);
    }
}

Notes:

• The above code does not handle cases where a single folder contains over 1,000 objects.
• Since the goal is to list objects and subfolders recursively, and folder keys always end with “/”, you should keep the delimiter as / for each recursive call.
• For each recursion, ObjectListing.getObjects returns the objects in the current “folder”, and ObjectListing.getCommonPrefixes returns its subfolders.

5. Delete Objects

Delete a Single Object

Delete a single object using WosClient.deleteObject:

WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);
wosClient.deleteObject("bucketname", "objectname");

Batch Delete Objects

Batch delete up to 1,000 objects per request using WosClient.deleteObjects:

WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

DeleteObjectsRequest deleteRequest = new DeleteObjectsRequest("bucketname");
wosClient.deleteObjects(deleteRequest);

6. Copy Object

Copying an object in WOS creates a duplicate of an existing object.

Use WosClient.copyObject to copy an object. You can assign new metadata and permissions, and conditional copy is supported.

Restrictions

• The user must have read access to the source object.
• Cross-region copy is not supported.
• Source object size must not exceed 5GB (simple copy is recommended for objects <1GB; use multipart copy for larger objects).
• Archived objects must be restored before copying.

Simple Copy

WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

try {
    CopyObjectResult result = wosClient.copyObject("sourcebucketname", "sourceobjectname", "destbucketname", "destobjectname");
    System.out.println("\t" + result.getStatusCode());
    System.out.println("\t" + result.getEtag());
} catch (WosException e) {
    // Copy failed
    System.out.println("HTTP Code: " + e.getResponseCode());
    System.out.println("Error Code: " + e.getErrorCode());
    System.out.println("Error Message: " + e.getErrorMessage());
    System.out.println("Request ID: " + e.getErrorRequestId());
    System.out.println("Host ID: " + e.getErrorHostId());
}

Overwrite Object Metadata During Copy

WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

CopyObjectRequest request = new CopyObjectRequest("sourcebucketname", "sourceobjectname", "destbucketname", "destobjectname");
// Enable metadata replacement
request.setReplaceMetadata(true);
ObjectMetadata newObjectMetadata = new ObjectMetadata();
newObjectMetadata.setContentType("image/jpeg");
newObjectMetadata.addUserMetadata("property", "property-value");
newObjectMetadata.setObjectStorageClass(StorageClassEnum.WARM);
request.setNewObjectMetadata(newObjectMetadata);
CopyObjectResult result = wosClient.copyObject(request);
System.out.println("\t" + result.getEtag());

Note:

• Use CopyObjectRequest.setReplaceMetadata(true) together with .setNewObjectMetadata.

Conditional Copy

You can specify one or more conditions; copy occurs only if all conditions are met.

Notes:

• The source object’s ETag is the object’s MD5 value.
• If the copy conditions are not met, HTTP 412 Precondition Failed is returned.
• Copy-Source-If-Modified-Since and Copy-Source-If-None-Match can be used together; Copy-Source-If-Unmodified-Since and Copy-Source-If-Match can be used together.

Example

WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

CopyObjectRequest request = new CopyObjectRequest("sourcebucketname", "sourceobjectname", "destbucketname", "destobjectname");

request.setIfModifiedSince(new SimpleDateFormat("yyyy-MM-dd").parse("2016-01-01"));
request.setIfNoneMatchTag("none-match-etag");

CopyObjectResult result = wosClient.copyObject(request);
System.out.println("\t" + result.getEtag());

Multipart Copy

Multipart copy is a special case of multipart upload, where each part is created by copying a part of an existing object. You can use WosClient.copyPart for this purpose. The example below demonstrates how to perform multipart copy for large objects:

String endPoint = "https://your-endpoint";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

final String destBucketName = "destbucketname";
final String destObjectKey = "destobjectname";
final String sourceBucketName = "sourcebucketname";
final String sourceObjectKey = "sourceobjectname";

// Create WosClient instance
final WosClient wosClient = new WosClient(ak, sk, endPoint, regionName);

// Initialize thread pool
ExecutorService executorService = Executors.newFixedThreadPool(20);

// Initiate multipart upload
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(destBucketName, destObjectKey);
InitiateMultipartUploadResult result = wosClient.initiateMultipartUpload(request);

final String uploadId = result.getUploadId();
System.out.println("\t" + uploadId + "\n");

// Get source object info
ObjectMetadata metadata = wosClient.getObjectMetadata(sourceBucketName, sourceObjectKey);
// Copy 100MB per part
long partSize = 100 * 1024 * 1024L;
long objectSize = metadata.getContentLength();

// Calculate number of parts
long partCount = objectSize % partSize == 0 ? objectSize / partSize : objectSize / partSize + 1;

final List<PartEtag> partEtags = Collections.synchronizedList(new ArrayList<PartEtag>());

// Perform concurrent part copy
for (int i = 0; i < partCount; i++) {
    // Range for each part
    final long rangeStart = i * partSize;
    final long rangeEnd = (i + 1 == partCount) ? objectSize - 1 : rangeStart + partSize - 1;
    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 = wosClient.copyPart(request);
                System.out.println("Part#" + partNumber + " done\n");
                partEtags.add(new PartEtag(result.getEtag(), result.getPartNumber()));
            } catch (WosException e) {
                e.printStackTrace();
            }
        }
    });
}

// Wait for completion
executorService.shutdown();
while (!executorService.isTerminated()) {
    try {
        executorService.awaitTermination(5, TimeUnit.SECONDS);
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
}

// Complete multipart upload
CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(destBucketName, destObjectKey, uploadId, partEtags);
wosClient.completeMultipartUpload(completeMultipartUploadRequest);