ComposeObjects Method

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

Syntax

 int ComposeObjects(char* lpszComposedObjectName);

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 of Wasabi 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, you must first specify the names of the objects you wish to compose together using the Objects property. When you call this method, the ComposedObjectName parameter determines what name is given to the resulting composed object. See the following code snippet for examples of how you can compose objects:

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

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

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

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

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

// Compose a composed object onto itself.
SetObjectNames("composed4.txt", "composed4.txt");
wasabi.ComposeObjects("composed4.txt");

Assume we have this helper method for the above code:

void SetObjectNames(params string[] names) {
    wasabi.Objects.Clear();
    foreach (string name in names) wasabi.Objects.Add(new WasabiObject(name));
}

As you can see, 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.
• Wasabi does not allow composing objects from multiple buckets together.
• Wasabi will not allow you to specify more than 32 object names in a single compose request.
• Wasabi will not allow you to compose more than 1024 original objects together. This is a transitive limit, you cannot circumvent it by composing together composed objects.

Wasabi does not make copies of data when composing objects, it uses references, so there are no extra data charges. Even if the original objects are deleted, a single copy of the data is kept until there are no longer any composed objects which reference it. Refer to the Wasabi documentation for more information.