IPWorks Cloud 2020 Kotlin Edition

Questions / Feedback?

ComposeObjects Method

Creates a composed object using multiple objects already on the server.

Syntax

public fun composeObjects(composedObjectName: String?)

Remarks

This method is used to compose objects on the server. Object composition is a server-side method of building an object by concatenating multiple existing objects together. This feature is a simpler alternative to the typical multipart-upload method of building objects.

A composed object looks and acts just like a regular object. However, its data is determined by its component objects (that is, the objects that make it up) and the order in which they are composed together.

To use this method, specify the names of the objects that should be composed together using the Objects property. When this method is called, the ComposedObjectName parameter determines what name is given to the resulting composed object. See the following code snippet for examples:

// Upload some objects to start with. Let's assume we have some text files to upload.
for (int i = 1; i <= 3; i++) {
    gstorage.LocalFile = "file" + i + ".txt";
    gstorage.CreateObject("file" + i + ".txt");
}

// Compose a new object.
SetObjectNames("file1.txt", "file2.txt", "file3.txt");
gstorage.ComposeObjects("composed1.txt");

// Compose a new object using a composed object.
SetObjectNames("file1.txt", "composed1.txt");
gstorage.ComposeObjects("composed2.txt");

// Compose onto an existing composed object. 
// (Similar to appending, but all server-side, no uploading needed.)
SetObjectNames("file1.txt", "file2.txt");
gstorage.ComposeObjects("composed3.txt");
SetObjectNames("composed3.txt", "file3.txt");
gstorage.ComposeObjects("composed3.txt");

// Compose a new object using the same object twice.
SetObjectNames("file1.txt", "file1.txt");
gstorage.ComposeObjects("composed4.txt");

// Compose a composed object onto itself.
SetObjectNames("composed4.txt", "composed4.txt");
gstorage.ComposeObjects("composed4.txt");
Assume we have this helper method for the above code:
void SetObjectNames(params string[] names) {
    gstorage.Objects.Clear();
    foreach (string name in names) gstorage.Objects.Add(new GStorageObject(name));
}

Object composition is a powerful and flexible feature. However, there are some things to keep in mind when doing object composition:

  • The order of the object names in the Objects property is the order that they will be concatenated in when they are composed.
  • Objects from multiple buckets cannot be composed together.
  • No more than 32 object names may be specified in a single compose request.

Copyright (c) 2021 /n software inc. - All rights reserved.
IPWorks Cloud 2020 Kotlin Edition - Version 20.0 [Build 7941]