Advanced Library Usage

Storage Cloud Quick Start

This shows how to use a virtual device attribute to upload content to, or download content from, the Oracle Storage Cloud Service.

To upload or download content from a virtual device, there must be an attribute, field, or action in the device model with type URI. For the Oracle Storage Cloud Service, the URI type corresponds to the class oracle.iot.client.StorageObject. When the attribute, field, or action of type URI is set to a StorageObject instance, the content is automatically synchronized with the Storage Cloud Service.

Uploading content

An instance of oracle.iot.client.StorageObject is first needed to upload a file from a device client or from an enterprise client. The StorageObject is created using the createStorageObject API in oracle.iot.client.Client, which is the base class for oracle.iot.client.enterprise.EnterpriseClient, oracle.iot.client.device.DirectlyConnectedDevice, and oracle.iot.client.device.GatewayDevice. The StorageObject names the object in storage, and provides the mime-type of the content. To set the input file, the oracle.iot.client.StorageObject API setInputPath(String) is used.

This example shows the typical use case from a DirectlyConnectedDevice. But the code for a GatewayDevice or EnterpriseClient is the same.

storageObject = directlyConnectedDevice.createStorageObject("mediaSnapshot.jpg", "image/jpg")
storageObject.setInputPath("../images/mediaSnapshot.jpg")
virtualDevice.set("snapshot", storageObject)

A StorageObject may also be set on an Alert field, or as an Action parameter, provided the type in the device model is URI.

Downloading content

In the virtualization API, the client is notified through an onChange event, onAlert event, or a call callback for an action. The value in the event is a StorageObject. To download the content, the output path is set on the StorageObject, and the content is synchronized by calling the StorageObject sync() API.

This example shows the typical use case from an onChange event. The code for an onAlert or for an action callback is much the same.

class OnChangeCallback(VirtualDevice.ChangeCallback):
    def onChange(self, event):
        namedValue = event.getNamedValue()
        storageObject = namedValue.getValue()
        # only download if image is less than 4M
        if storageObject.getLength() < 4 * 1024L * 1024L:
            try:
                storageObject.setOutputPath("../downloads/"+storageObject.getName())
                storageObject.sync()
            except Exception as e:
                print("cannot create file for download")

virtualDevice.setOnChange("snapshot", OnChangeCallback())

Checking synchronization status

A StorageObject is a reference to some content in the Storage Cloud. The content can be in sync with the storage cloud, not in sync with the storage cloud, or in process of being sync’d with the storage cloud. The synchronization happens on a separate thread, but can be monitored by setting a SyncCallback with setOnSync.

For the upload case, set the SyncCallback on the storage object before setting the virtual device attribute. For the download case, set the SyncCallback on the storage object from within the onChange callback.

class SyncCallback(StorageObject.SyncCallback):
    def onSync(self, event):
        storageObject = event.getStorageObject()
        if storageObject.getSyncStatus() == StorageObject.SyncStatus.IN_SYNC:
             # image was uploaded and can be deleted
        elif storageObject.getSyncStatus() == StorageObject.SyncStatus.SYNC_FAILED:
             # image was not uploaded, take action!