Readme

Introduction

The Logical Labs Rackspace Cloud Files module gives Titanium developers easy access to the Rackspace Cloud Files service.

The module defines the following classes:

Client
Container
Object

The names of these classes follow the Rackspace naming convention. Objects are basically files. A container is essentially a folder to organize files.

The client is the entity that provides the connection to the Rackspace Cloud Files servers. You use it to authenticate and to query and change account details.

Usage

The first step in using the Logical Labs Rackspace Cloud Files module is to load the module, create a client object, and authenticate to the Cloud Files service:

var CloudFiles = require('com.logicallabs.rackspace.cloudfiles');

var client = CloudFiles.createClient();

client.authenticate({
    username: <your username>,
    apikey: <your API key>,
    success: function(e) { ... },
    failure: function(e) { ... }
});

The authentication happens in an asynchronous manner and the result will be reported via the success or failure function. Once you receive the call to the success function, the client is ready to go.

To query the containers available in the account, use the getContainers function:

client.getContainers({
    success: function(e) { ... },
    error: function(e) { ... }
});

This function, like most other functions in this module, is asynchronous and will report the result by calling the success or error callback function you provide. In this case, the success function will receive an array of Container objects. You can use the getObjects method to get the objects inside the container:

container.getObjects({
    success: function(e) { ... },
    error: function(e) { ... }
});

This only downloads the names and metadata of the objects, not their actual content. Use the download function to download the content of an object into a file:

dstFile = Ti.Filesystem.getFile(
                Ti.Filesystem.applicationDataDirectory +
                'localFileName'
            );

object.download({
    file: dstFile,
    success: function(e) { ... },
    error: function(e) { ... }
    progress: function(e) { ... }
});

The progress parameter is optional; if specified, the module will call the provided function periodically as the download progresses with a progress indicator value between 0.0 and 1.0.

You can create new objects in a container using the uploadObject function. This function reads the content either from a Ti.Blob object:

sourceFile = Ti.Filesystem.getFile(..);

container.uploadObject({
    name: <object name>,
    media: sourceFile.read(),
    success: function(e) { ... },
    error: function(e) { ... }
    progress: function(e) { ... }
});

or from a file:

sourceFile = Ti.Filesystem.getFile(..);

container.uploadObject({
    name: <object name>,
    file: sourceFile,
    success: function(e) { ... },
    error: function(e) { ... }
    progress: function(e) { ... }
});

If the container is CDN-enabled, you can download the object from the CDN using the downloadFromCdn function.

if (object.container.isCdnEnabled()) {
    object.downloadFromCdn({
        file: dstFile,
        success: function(e) { ... },
        error: function(e) { ... }
        progress: function(e) { ... }
    }) 
}

Note that the isCdnEnabled function reports the CDN status of the container as far as the module knows. The Rackspace Cloud Files API does not automatically provide CDN related information to every query related to container, so it is possible that the module's internal information is not in sync with the actual status of the container. See the "Property Caching" section later in this Readme for more details on this. Call the getCdnMetadata function to retrieve the CDN URI and other CDN related information of the container before you try to access an object through the CDN:

container.getCdnMetadata({
    success: function(e) { ... },
    error: function(e) { ... }
});

Property Caching

Some properties of the Client, Container, and Object objects are representations of values that may change over time. For example the containerCount represents the number of containers that belong to an account, and this number changes every time container is added or deleted. These properties are not refreshed every time you read them as that would require somewhat time consuming communication with the cloud server. Instead, these properties are refreshed whenever you make a function call that results in a response from the server that contains the current value of these properties. For example the containerCount is refreshed every time the getAccountMetadata function is called.

Similarly, CDN related information is not automatically available to the module. Use the getCdnMetadata function to retrieve/refresh the CDN status of a container.

Note that even calling a function that updates one or more of the properties in the cloud will not automatically update the local properties. For example, the updateAccountMetadata will only update the account's metadata in the cloud (assuming the connection to the cloud server was successful), it will not update the containerCount or even the metadata -- you must call the getAccountMetadata function to achieve that.

Asynchronous Operations

Many of the functions provided by this module are asynchronous in nature, since they need to communicate with a remote server in order to perform the requested action. These functions always take success and error callback functions as parameters, which are called upon successful or unsuccessful completion of the operation. Some of the functions also have a progress function parameter, which is called to report progress of the operation.

All of these functions always receive a source parameter that is set to the object that the original function belongs to. Often this is the only parameter to the success function, since the result of the operation is reflected in the properties of said object; see the "Property Caching" section above for more details on this.

Automatic Re-Authentication

Every Rackspace Cloud Files operation except downloading from the CDN network requires an authentication token. The module acquires this token when you call the authenticate function, and caches it internally for subsequent uses so that you do not need to provide it as a parameter to any function calls.

This token typically expires 24 hours after it was issued (not 24 hours after you call authenticate -- that function may retrieve a token created earlier), and it may be explicitly revoked before it expires. Therefore, an operation trying to use the previously cached token may fail with an "unauthorized" error.

The module will, by default, automatically attempt to re-authenticate when this happens, and then re-attempt the originally requested operation. This operation may fail again, with the same or a different error. If that happens, even if the error is "unauthorized", the module will not attempt authorization again. Instead, the error handler callback provided with the original function call will be called, and beside the usual errorCode and errorMessage an authResult parameter will also be provided -- this authResult parameter holds the results of the automatic re-authentication.

If you do not want the module to perform automatic re-authentication, set the autoAuth property to false.

Issues and Limitations

Change Log

Version 1.0.0

First release

Version 1.0.1

Added region parameter to authenticate and createClient functions.
Added region property to Client object.

Author

Zsombor Papp, Logical Labs titanium@logicallabs.com

License

See LICENSE file included with the module for all terms and conditions specific to this module.

General terms and conditions for all Logical Labs Titanium Modules can be found here: http://www.logicallabs.com/logical-labs-titanium-module-terms-conditions

Logical Labs Rackspace Cloud Files

APIs