If you want to use this feature, first of all you have to modify your config.xml file and add a new Feature named ObjectStorage within Requirements. For example, if you use XML to set up the configuration of your widget, your code should look similar to the following one. Note that we have also added a preference that will be useful to store the KeyStone server URL.

<?xml version='1.0' encoding='UTF-8'?>
<widget xmlns="http://wirecloud.conwet.fi.upm.es/ns/macdescription/1" vendor="Wirecloud" name="objectstorage-test-widget" version="1.0">
  <details>
    <title>Wirecloud Object Storage API test widget</title>
    <authors>aarranz</authors>
    <email>aarranz@conwet.com</email>
    <image>images/catalogue.png</image>
    <smartphoneimage>images/catalogue_iphone.png</smartphoneimage>
    <description>This widget is used to test whether the Object Storage API is usable by widgets</description>
    <doc>doc/index.html</doc>
  </details>
  <requirements>
    <feature name="ObjectStorage"/>
  </requirements>
  <preferences>
    <preference name="keystone_url" type="text" label="Keystone Server" description="Keystone Server where the Object Storage server to use for testing the integration between Wirecloud and the Object Storage GE is registered" default="https://cloud.lab.fiware.org/keystone"/>
  </preferences>
  <wiring/>
  <contents src="test.html" contenttype="text/html" charset="utf-8" useplatformstyle="true"/>
  <rendering height="24" width="6"/>
</widget>

To start using the ObjectStorage, first you have to set up the connection with the KeyStone server. To do so, you should create a new KeystoneAPI:

var keystone = new KeystoneAPI(url, options)

See the ObjectStorage Javascript API documentation for the full list of supported options but, as summary, the url is the ObjectStorage Server location. Also, if you are connecting to a ObjectStorage instance using the IdM authentication, you will need to pass the required authentication credentials. This can be accomplished in two ways:

• Making use of the token option and passing directly the required Authentication header
• Making use of the use_user_fiware_token option to make the ObjectStorage use the token obtained by WireCloud from the IdM

This example shows you how to connect with the KeyStone server using the resources available in the FIWARE Testbed. Note that the Keystone URL used is the one obtained from the preferences:

var keystone = new KeystoneAPI(MashupPlatform.prefs.get('keystone_url'), {
    use_user_fiware_token: true
});

Once that you are connected with the KeyStone server, you have to take into account is that a user can use several tenants to store the information. To get the list of available tenants for a user, you can use the getTenants function:

keystone.getTenants([options])

The options argument allows you to set two callbacks:

• onSuccess is called when the request finishes successfully. This function will receive a dictionary with the field tenants that contains all the available tenants for the user that make the request
• onFailure is called when the request finish with errors

In the following example, we call the function with both callbacks. If the request finish successfully, we will show the id of the first available tenant. Otherwise, we will show a message error:

keystone.getTenants({
    onSuccess: function(data) {
        document.getElementById('tenantId').textContent = data.tenants[0].id;
    },
    onFailure: function () {
        document.getElementById('tenantId').textContent = 'Fail';
    }
});

When you have selected the tenant that you want to use, you must get an authentication token using the getAuthToken function:

keystone.getAuthToken([options])

options argument include the following fields:

• tenantName: name of the tenant to be associated to the generated token. Both the tenantId and tenantName attributes are optional, but should not be specified together
• tenantId: The id of the tenant to be associated to the generated token. Both the 'tenantId' and 'tenantName' attributes are optional, but should not be specified together
• onSuccess: called when the request finishes successfully. This function will receive two parameters:
  • new_token: the new token obtained that you can use to access the ObjectStorage
  • data: the catalogue of available services for the tenant
• onFailure: called when the request finish with errors

The next snippet shows you how to use this function. In this case we will use the tenant id obtained in the previous code. Note that we will also process the data parameter in order to get the ObjectStorage URL:

keystone.getAuthToken({
    tenantId: data.tenants[0].id,
    onSuccess: function (new_token, data) {
        for (i = 0; i < data.access.serviceCatalog.length; i++) {
            if (data.access.serviceCatalog[i].type === 'object-store') {
                object_storage = data.access.serviceCatalog[i].endpoints[0].publicURL;
            }
        }
    },
    onFailure: function () {
        document.getElementById('api_token').textContent = 'Fail';
    }
});

Once that you have the URL of the ObjectStorage server, we can connect to it. To do so, we must use the following function:

objectStorage = ObjectStorageAPI(url)

In our case we have saved the ObjectStorage Server URL in the object_storage variable, so our code should be the following one:

objectStorage = ObjectStorageAPI(object_storage)

When we are connected to a ObjectStorage Server, we are able to list all the content available in a container. To do so, we should use the listContainer function:

objectStorage.listContainer(container[, options])

The container argument is the name of the container while the options argument should contain the following fields:

• token: The token obtained previously in the getAuthToken function
• onSuccess: called when the request finishes successfully. This function receives as argument the list of available files in the container
• onFailure: called when the request finish with errors

In the next example, we will show we will get the available files in the integrationTests container, and we will show the name of the first one.

objectStorage.listContainer('integrationTests', {
    token: token,

    onSuccess: function(file_list) {
        document.getElementById('file_name').textContent = file_list[0].name;
    },

    onFailure: function () {
        document.getElementById('file_count').textContent = 'Fail';
    }
});

If you are connected to the ObjectStorage, you can also upload a file easily. To do so, you must use the uploadFile function:

objectStorage.uploadFile(container, file[, options])

container is the name where the file is going to be uploaded, while file is the content to be uploaded. The options argument should contain the following fields:

• token: The token obtained previously in the getAuthToken function
• file_name: The name used to save the uploaded content in the container
• onSuccess: called when the request finishes successfully. This function does not receive any arguments
• onFailure: called when the request finish with errors

Here you can see how to upload a text file containing "Hello world!".

var blob = new Blob(["Hello world!"], { type: "text/plain" });
objectStorage.uploadFile('integrationTests', blob, {
    token: token,
    file_name: 'test1.txt',
    onSuccess: function() {
        document.getElementById('file_upload').textContent = 'OK';
    },
    onFailure: function () {
        document.getElementById('file_upload').textContent = 'Fail';
    }
});

It's useful to upload a file, but in some occasions you will want to delete it. To do so, you have to use the deleteFile function:

objectStorage.deleteFile(container, file_name[, options])

container is the name of the container where the file is going to be deleted while file_name is the name of the file to delete. The options argument should contain the following fields:

• token: The token obtained previously in the getAuthToken function
• onSuccess: called when the request finishes successfully. This function does not receive any arguments
• onFailure: called when the request finish with errors

The following example shows how to delete the file that we have created in the previous step:

objectStorage.deleteFile('integrationTests', file_name, {
    token: token,
    onSuccess: function() {
        document.getElementById('file_deletion').textContent = 'OK';
    },
    onFailure: function () {
        document.getElementById('file_deletion').textContent = 'Fail';
    }
});