Use Media with the Client Libraries

Using media with the Oracle IoT Cloud Service Device Libraries, such as images, videos, or other large binaries, involves the Oracle Storage Cloud Service.

To allow links and references in device model attributes and device model format fields, the URI type has been added to the list of device model attribute types. This URI type is encoded as a JSON String for communication, but adheres to the format restrictions of the Universal Resource Identifier format as defined in RFC 3986. A URI provides a standard syntax, while at the same time allowing flexibility in defining the semantics of what a resource is. The basic syntax of a URI is[scheme:]scheme-specific-part[#fragment]. With the Java SE client libraries, this may be represented as a  class. For other client libraries, use an equivalent data type, or a string if none is available.

Storage Cloud Service

The Oracle Storage Cloud Service must be used to store media provided by the client and referenced within device model attributes. See the Oracle Storage Cloud Service documentation for more details. Note that the administrator may want to establish user accounts for the specific purposes of device media storage and configure these accounts to restrict access to only specific containers within the cloud service. Storage service credentials should be independent of other storage service credentials provisioned within the Oracle cloud.

The following fields need to be provisioned:

  • The storage cloud service server name (for example,

  • The storage service identity (for example, Storage-a210401)

  • The storage service container (for example, MediaStorageContainer)

  • The storage service username

  • The storage service password

Device Virtualization in the Java Client Libraries

Using device virtualization, an application first creates an oracle.iot.client.StorageObject object via the Client.createStorageObject() method. The name parameter is used as the unique name of the object in the storage cloud REST API (i.e., the 'object' in /v1/{account}/{container}/{object}).

If content is being uploaded, the application sets the input path on the StorageObject via the setInputPath() method. The storage object is then set as the value of an attribute in the virtual device, and the attribute has to have type URI in the device model. The content is then uploaded. The DataMessage for the attribute, format or field is not sent until the content upload is complete. An error from uploading content to the storage cloud will result in an onError() callback to the virtual device.

If content is being downloaded, the application sets the output path on the StorageObject via the setOutputPath() method, and then calls sync() on the storage object. The sync() call does not block. The caller can then add a callback for sync events to the storage object.