Overview (Java SE Messaging API Reference for Oracle Internet of Things Cloud Service Client Software Library)

Packages
Package	Description
com.oracle.iot.client
com.oracle.iot.client.device
com.oracle.iot.client.device.persistence
com.oracle.iot.client.device.util	Utility classes that may be used with the oracle.iot.client.device package.
com.oracle.iot.client.enterprise
com.oracle.iot.client.message	Defines messages that can be exchanged between Server and Client and vice versa.
com.oracle.iot.client.trust	API for handling trust material used for activation and authentication to the Oracle IoT Cloud Service.
com.oracle.iot.client.util

The device and enterprise client libraries simplify working with the Oracle IoT Cloud Service. These client libraries are a low–level abstraction over top of messages and REST APIs. Device clients are primarily concerned with sending data and alert messages to the cloud service, and acting upon requests from the cloud service. Enterprise clients are primarily concerned with monitor and control of device endpoints.

Configuration

The client must have a runtime configuration in order to communicate with the cloud service. This runtime configuration includes the IoT Cloud Service host, the identifier of the device or enterprise integration the client represents, and the shared secret of the device or enterprise integration.

The configuration is created by running the com.oracle.iot.client.impl.trust.TrustedAssetsProvisioner tool. This tool creates an encrypted file that is used when running the client application. Usage is available by running the tool without arguments.

Device and Enterprise Clients

Prerequisites

Register your device and/or enterprise application with the Cloud Service.
Provision the device with the credentials obtained from above.
Optionally provision the device model.

Device Client Quick Start

The following steps must be taken to run a device-client application. The example shows a com.oracle.iot.client.GatewayDevice. A com.oracle.iot.client.DirectlyConnectedDevice is identical, except for registering indirectly-connected devices.

1. Initialize device client


    com.oracle.iot.client.GatewayDevice gw =
        new com.oracle.iot.client.GatewayDevice(configurationFilePath, password);

2. Activate the device


     if (!gw.isActivated()) {
         gw.activate();
     }

3. Register indirectly-connected devices


     // create meta-data with the indirectly-connected device's
     // manufacturer, model, and serial number
     Map<String,String> metaData = new HashMap<String, String>();
     metaData.put(com.oracle.iot.client.GatewayDevice.MANUFACTURER, "A Manufacturer");
     metaData.put(com.oracle.iot.client.GatewayDevice.MODEL_NUMBER, "MN-xxxx-xxxx");
     metaData.put(com.oracle.iot.client.GatewayDevice.SERIAL_NUMBER, "SN-yyyyyyyy");
     // register it
     String deviceId = gw.registerDevice(hardwareId, metaData, deviceModelUrn);

4. Register handler for attributes and actions


     // RequestDispatcher is a utility that simplifies handling of request messages.
     // RequestMessages can be handled without the RequestDispatcher by
     // branching on the RequestMessage getEndpointId() and getURL().
     RequestDispatcher requestDispatcher = RequestDispatcher.getInstance();
     requestDispatcher.registerRequestHandler(deviceId,
          "myWritableAttribute", new RequestHandler() {
               public ResponseMessage handleRequest(RequestMessage requestMessage) {
                   // Handle the request. The data, if any, is in the requestMessage body.
                   // Return a ResponseMessage
               }
          }
       );

5. Send data from the indirectly-connected device


    // create a DataMessage
    DataMessage dataMessage = new DataMessage.Builder()
        .format(DATA_FORMAT)
        .source(dcd.getEndpointId())
        .dataItem(ATTRIBUTE, value)
        .build();
    // send the message
    gw.send(dataMessage);

6. Receive and dispatch requests from the server


    // RequestDispatcher is a utility that simplifies handling of request messages.
    // RequestMessages can be handled without the RequestDispatcher by
    // branching on the RequestMessage getEndpointId() and getURL().
    RequestDispatcher requestDispatcher = RequestDispatcher.getInstance();
    RequestMessage requestMessage = null;
    while((requestMessage = gw.receive()) != null) {
        ResponseMessage response = requestDispatcher.dispatch(requestMessage);
        gw.send(response);    
    }

7. Dispose the device client


     gw.close();

Enterprise Client Quick Start

The following steps must be taken to run an enterprise-client application.

1. Initialize enterprise client


    EnterpriseClient ec =
        EnterpriseClient.newClient(configurationFilePath, password);

2. Select a device


     Filter filter = Filter.eq(Device.Field.MANUFACTURER.alias(), "MyCompany");
     Pageable<Device> devices = ec.getDevices(null, filter);
     while (devices.hasMore()) {
         devices.next();
         for (Device d: devices.elements()) {
             // inspect & select
         }
     }

3. Monitor a device


    MessageEnumerator me = new MessageEnumerator(ec);
    me.setListener(device.getId(), null, new MessageListener() {
        public void notify(Collection<Message> msgReceived) {
            // process received messages
        }
    }

4. Get the value of a field


    String value = device.getValue(Device.Field.MODEL_NUMBER);

5. List the resources of a device


    ResourceEnumerator re = new ResourceEnumerator(ec, device);
    Pageable<Resource> resources = re.getResources();
    while (resources.hasMore()) {
        resources = resources.next();
        for (Resource r: resources.elements()) {
            // inspect & select
        }
    }

5. Dispose the enterprise client


    enterpriseClient.close();

Storage Cloud Quick Start

This shows how to use the messaging API to upload content to, or download content from, the Oracle Storage Cloud Service. To upload or download content, there must be an attribute, field, or action in the device model with type URI. When creating a DataItem for an attribute, field, or action of type URI, the value is set to the URI of the content in cloud storage.

Uploading content

An instance of com.oracle.iot.client.StorageObject is first needed to upload the content. The StorageObject is created using the createStorageObject(String,String) API in com.oracle.iot.client.device.DirectlyConnectedDevice, which is also the base class com.oracle.iot.client.device.GatewayDevice. A StorageObject names the object in storage, and provides the mime-type of the content.

To set the input to upload, the com.oracle.iot.client.StorageObject API setInputStream(InputStream) is used. Note that the StorageDispatcher is a utility for putting the sync in the background. Progress can be monitored by setting a ProgressCallback on the StorageDispatcher. StorageDispatcher is an alternative to using the StorageObject sync() API.


    MessageDispatcher md = MessageDispatcher.getMessageDispatcher(dcd);

    StorageConnection sc = dcd.getStorageConnection();
    StorageDispatcher sd = StorageDispatcher.getStorageDispatcher(sc);

    sd.setProgressCallback(new ProgressCallback() {
        public void progress(Progress progress) {
            StorageObject storageObject =
                progress.getStorageObject();
            if(progress.getState() == State.COMPLETED) {
                // image was uploaded and can be deleted
                // Send message with the storage object name
                DataMessage.Builder messageBuilder =
                        new DataMessage.Builder()
                                .format(CONTENT_MODEL_URN + ":attributes")
                                .source(endpointId)
                                .dataItem(CONTENT_ATTRIBUTE, storageObject.getURI());
                md.queue(messageBuilder.build());
            } else if (progress.getState() == State.IN_PROGRESS) {
                // if taking too long, cancel:
                sd.cancel(storageObject);
            }
        }
    });
    StorageObject storageObject = dcd.createStorageObject("snapshot.jpg", "image/jpeg");
    storageObject.setInputStream(new FileInputStream("snapshot.jpg"));
    sd.queue(storageObject);

Enterprise Client Example

Monitor the device.


    EnterpriseStorageConnection esc = new EnterpriseStorageConnection(enterpriseClient);
    StorageConnection sc = esc.getStorageConnection();
    StorageDispatcher sd = StorageDispatcher.getStorageDispatcher(sc);

    String uri;

    //Process received messages:
    for (Message message : msgReceived) {
        if (message instanceof DataMessage) {
            DataMessage dm = (DataMessage)message;
            List<DataItem<?>> items = dm.getDataItems();
            for (DataItem<?> di: items) {
                if (di.getKey() == CONTENT_ATTRIBUTE) {
                    uri = di.getValue().toString();
                    StorageObject so = esc.createStorageObject(uri);
                    sd.queue(so);
                } 
            }
        }
    }

Device and Enterprise Client System Properties

Key	Meaning
`com.oracle.iot.client.enterprise.message_polling_interval`	Default: 3000 milliseconds The amount of delay, in milliseconds, between polls for messages by the MessagePoller. This setting affects how often a MessageEnumerator.MessageListener instance may be called.
`com.oracle.iot.client.enterprise.message_polling_limit`	Default: 10 The maximum number of messages to return on a single poll by the MessagePoller. The value will be clamped between 10 and 200, inclusive.
`com.oracle.iot.client.enterprise.message_refill_count`	Default: 10 messages The number of messages in each page the message enumerator retrives from the server.
`com.oracle.iot.client.device.allow_draft_device_models`	Default: false If true, a device can be activated without a device model on the server for the device. The server will create a draft device model which contains no attributes. A draft device model allows devices to be brought on-line ahead of the server being provisioned with the device model. However, attempts by the device to set an attribute when using a draft device model will fail.
`oracle.iot.client.device.dispatcher_polling_interval`	Default: 3 seconds The polling interval, in seconds, for message dispatching. If a message is not sent to the server within this timeout, an empty message will be sent in order to solicit request messages that may be queued in the server.
`oracle.iot.client.device.dispatcher_max_queue_size`	Default: 10000 Total messages to queue. Attempts to send messages when the queue is full will result in an error.
`oracle.iot.client.device.dispatcher_max_messages_per_connection`	Default: 100 Maximum number of outgoing messages to send in one payload per HTTPS connection to the server.
`oracle.iot.client.device.request_buffer_size`	Default: 4192 bytes The total size all of incoming messages received from the server that have not been handled by callbacks to the application.
`com.oracle.iot.client.disable_long_polling`	Default: false Long polling is used by default, set this to true to disable it.
`com.oracle.iot.client.long_polling_timeout_offset`	Default: 100 milliseconds The time, in milliseconds, added to the receive timeout given by the application and then used for the client transport timeout.
`oracle.iot.client.device.send_receive_timeout`	Default: 100 milliseconds Only used when long polling is disabled. The minimum time, in milliseconds, since the last send before polling the server for incoming messages if the receive buffer is empty. A larger value may cause a delay in the receipt of incoming messages, but will cause less network overhead. A value of zero will cause the library to skip the poll for incoming messages when calling receive if the receive buffer is empty.
`oracle.iot.client.http_response_timeout`	Default: 15000 milliseconds Only used when long polling is disabled. The amount of time, in milliseconds, to wait for the server to respond to an HTTPS request.
`oracle.iot.client.pretty_print_messages`	Default: true Controls whether or not logged messages should be pretty printed. Pretty printing the messages makes the JSON easier to read. By default, pretty printing is enabled. Set this property to false to disable pretty printing for a more compact view of the logged messages.
`oracle.iot.client.network_cost`	Default: ETHERNET Used by the "batchByCost" device function, set this property to the type of connected network. The property may be set from the application code; for example, when the type of connected network changes.
`oracle.iot.client.configuration_path`	Default: current directory The directory where the simple trusted assets manager will store activation parameters.
`oracle.iot.client.disable_storage_object_prefix`	Default: false Disable the prefixing the storage object's name with the device's client ID and a directory separator.
`oracle.iot.client.device.request_dispatcher_thread_pool_size`	Default: 1 Number of threads created for dispatching request messages so that request handlers can be executed in parallel. This number should be specified as greater than one, else it will be ignored and the default value of one will be used for request handler thread pool size. Request Dispatcher should be used for request handling for this setting to be effective.
`com.oracle.iot.client.device.persistence_directory`	Default: System property user.dir The directory that is used for local persistence.
`com.oracle.iot.client.device.persistence_db_name`	Default: persistence_store The name of the database used for persisting data.
`com.oracle.iot.client.device.persistence_enabled`	Default: true If true, the client library will persist data.
`com.oracle.iot.client.device.isolation_level`	Default: java.sql.Connection.TRANSACTION_READ_UNCOMMITTED Get the transaction isolation level for SQL database persistence.