Package com.amazonaws.services.iot.client

Class AWSIotDevice

  • public class AWSIotDevice
extends AbstractAwsIotDevice
    This class encapsulates all the functionalities that one can use to interact with AWS IoT device shadows in the cloud. For more information about AWS IoT device shadow, please refer to the AWS IoT developer guide.

    AWSIotDevice represents a device that is one-to-one mapped with the AWS IoT device shadow. The linkage is created through the shadow name that is passed into the constructor.

    There are two typical ways of using AWSIotDevice. One is to extend AWSIotDevice and provide device attributes that are to be synchronized with the shadow and their accessor methods (getters and setters). The other way is to use the get/update/delete methods provided in this class to directly access the shadow document. The first approach is easy to implement and should work for most of the use cases; the second approach provides the user the ability of directly accessing the data (document) stored on the device shadow, which is very flexible, however the user is responsible for parsing the shadow document encoded in JSON, and providing shadow-compatible document in update calls. It's also possible to use both approaches in a same application.

    To leverage the synchronization function provided by the library, one needs to extend AWSIotDevice. Device attributes that are to be kept in sync with the shadow must be annotated with AWSIotDeviceProperty. One should also provide getter functions for these annotated attributes to be reported to the shadow as well as setter functions to accept updates from the shadow. A simplified example is like this 

         public class SomeDevice extends AWSIotDevice {
        @AWSIotDeviceProperty
         boolean switch;
         
         public boolean getSwitch() {
              // read from the device and return the value to be reported to the shadow
              return ...;
         }
         
         public void setSwitch(boolean requestedState) {
              // write to the device with the requested value from the shadow
         }
     }

    To linked the above class with the shadow, one could do like so 

         AWSIotMqttClient client = new AWSIotMqttClient(...);
     
     SomeDevice someDevice = new SomeDevice(thingName);
     
     client.attach(someDevice);
     
     client.connect();

    To access the shadow directly, one could do as the below. All the methods in this class are thread-safe, therefore can be called in different user threads. 

         AWSIotMqttClient client = new AWSIotMqttClient(...);
     
     AWSIotDevice awsIotDevice = new AWSIotDevice(thingName);
     
     client.attach(awsIotDevice);
     
     client.connect();
     
     ...
     String jsonDocument = awsIotDevice.get();
     ...
     client.update(jsonDocument);
     ...

    The library contains sample applications that demonstrate how each of these two methods can be used.

    • Constructor Detail

      • AWSIotDevice

        public AWSIotDevice​(String thingName)
        Instantiates a new device instance.
        Parameters:
        thingName - the thing name

    • Method Detail

      • getReportInterval

        public long getReportInterval()
        Gets the device report interval.
        Overrides:
        getReportInterval in class AbstractAwsIotDevice
        Returns:
        the report interval in milliseconds.

      • setReportInterval

        public void setReportInterval​(long reportInterval)
        Sets the device report interval in milliseconds. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call. The default interval is 3,000ms. Setting it to 0 will disable reporting.
        Overrides:
        setReportInterval in class AbstractAwsIotDevice
        Parameters:
        reportInterval - the new report interval

      • isEnableVersioning

        public boolean isEnableVersioning()
        Checks if versioning is enabled for device updates.
        Overrides:
        isEnableVersioning in class AbstractAwsIotDevice
        Returns:
        true, if versioning is enabled for device updates.

      • setEnableVersioning

        public void setEnableVersioning​(boolean enableVersioning)
        Sets the device update versioning to be enabled or disabled. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call.
        Overrides:
        setEnableVersioning in class AbstractAwsIotDevice
        Parameters:
        enableVersioning - true to enable device update versioning; false to disable.

      • getDeviceReportQos

        public AWSIotQos getDeviceReportQos()
        Gets the MQTT QoS level for publishing the device report. The default QoS is QoS 0.
        Overrides:
        getDeviceReportQos in class AbstractAwsIotDevice
        Returns:
        the device report QoS

      • getShadowUpdateQos

        public AWSIotQos getShadowUpdateQos()
        Gets the MQTT QoS level for subscribing to shadow updates. The default QoS is QoS 0.
        Overrides:
        getShadowUpdateQos in class AbstractAwsIotDevice
        Returns:
        the shadow update QoS

      • getMethodQos

        public AWSIotQos getMethodQos()
        Gets the MQTT QoS level for sending the shadow methods, namely Get, Update, and Delete. The default QoS is QoS 0.
        Overrides:
        getMethodQos in class AbstractAwsIotDevice
        Returns:
        the QoS level for sending shadow methods.

      • getMethodAckQos

        public AWSIotQos getMethodAckQos()
        Gets the MQTT QoS level for subscribing to acknowledgement messages of shadow methods. The default QoS is QoS 0.
        Overrides:
        getMethodAckQos in class AbstractAwsIotDevice
        Returns:
        the QoS level for subscribing to acknowledgement messages.

      • setMethodAckQos

        public void setMethodAckQos​(AWSIotQos methodAckQos)
        Sets the MQTT QoS level for subscribing to acknowledgement messages of shadow methods. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call.
        Overrides:
        setMethodAckQos in class AbstractAwsIotDevice
        Parameters:
        methodAckQos - the new QoS level for subscribing to acknowledgement messages.

      • get

        public String get()
           throws AWSIotException
        Retrieves the latest state stored in the thing shadow. This method returns the full JSON document, including meta data. This is a blocking call, so the calling thread will be blocked until the operation succeeded or failed.

        Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

        Overrides:
        get in class AbstractAwsIotDevice
        Returns:
        the JSON document of the device state
        Throws:
        AWSIotException - exception thrown if the operation fails

      • get

        public String get​(long timeout)
           throws AWSIotException,
                  AWSIotTimeoutException
        Retrieves the latest state stored in the thing shadow. This method returns the full JSON document, including meta data. This is a blocking call, so the calling thread will be blocked until the operation succeeded, failed, or timed out.
        Overrides:
        get in class AbstractAwsIotDevice
        Parameters:
        timeout - the timeout in milliseconds that the calling thread will wait
        Returns:
        the JSON document of the device state
        Throws:
        AWSIotException - exception thrown if the operation fails
        AWSIotTimeoutException - exception thrown if the operation times out

      • get

        public void get​(AWSIotMessage message,
                long timeout)
         throws AWSIotException
        Retrieves the latest state stored in the thing shadow. This method returns the full JSON document, including meta data. This is a non-blocking call, so it immediately returns once is the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively.
        Overrides:
        get in class AbstractAwsIotDevice
        Parameters:
        message - the message object contains callback functions; if the call is successful, the full JSON document of the device state will be stored in the payload field of message.
        timeout - the timeout in milliseconds for the operation to be considered timed out
        Throws:
        AWSIotException - exception thrown if the operation fails

      • update

        public void update​(String jsonState)
            throws AWSIotException
        Updates the content of a thing shadow with the data provided in the request. This is a blocking call, so the calling thread will be blocked until the operation succeeded or failed.

        Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

        Overrides:
        update in class AbstractAwsIotDevice
        Parameters:
        jsonState - the JSON document of the new device state
        Throws:
        AWSIotException - exception thrown if the operation fails

      • update

        public void update​(String jsonState,
                   long timeout)
            throws AWSIotException,
                   AWSIotTimeoutException
        Updates the content of a thing shadow with the data provided in the request. This is a blocking call, so the calling thread will be blocked until the operation succeeded, failed, or timed out.
        Overrides:
        update in class AbstractAwsIotDevice
        Parameters:
        jsonState - the JSON document of the new device state
        timeout - the timeout in milliseconds that the calling thread will wait
        Throws:
        AWSIotException - exception thrown if the operation fails
        AWSIotTimeoutException - exception thrown if the operation times out

      • update

        public void update​(AWSIotMessage message,
                   long timeout)
            throws AWSIotException
        Updates the content of a thing shadow with the data provided in the request. This is a non-blocking call, so it immediately returns once is the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively.
        Overrides:
        update in class AbstractAwsIotDevice
        Parameters:
        message - the message object contains callback functions
        timeout - the timeout in milliseconds for the operation to be considered timed out
        Throws:
        AWSIotException - exception thrown if the operation fails

      • delete

        public void delete()
            throws AWSIotException
        Deletes the content of a thing shadow. This is a blocking call, so the calling thread will be blocked until the operation succeeded or failed.

        Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

        Overrides:
        delete in class AbstractAwsIotDevice
        Throws:
        AWSIotException - exception thrown if the operation fails

      • delete

        public void delete​(long timeout)
            throws AWSIotException,
                   AWSIotTimeoutException
        Deletes the content of a thing shadow. This is a blocking call, so the calling thread will be blocked until the operation succeeded, failed, or timed out.
        Overrides:
        delete in class AbstractAwsIotDevice
        Parameters:
        timeout - the timeout in milliseconds that the calling thread will wait
        Throws:
        AWSIotException - exception thrown if the operation fails
        AWSIotTimeoutException - exception thrown if the operation times out

      • delete

        public void delete​(AWSIotMessage message,
                   long timeout)
            throws AWSIotException
        Deletes the content of a thing shadow. This is a non-blocking call, so it immediately returns once is the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively.
        Overrides:
        delete in class AbstractAwsIotDevice
        Parameters:
        message - the message object contains callback functions
        timeout - the timeout in milliseconds for the operation to be considered timed out
        Throws:
        AWSIotException - exception thrown if the operation fails

      • onShadowUpdate

        public void onShadowUpdate​(String jsonState)
        This function handles update messages received from the shadow. By default, it invokes the setter methods provided for the annotated device attributes. When there are multiple attribute changes received in one shadow update, the order of invoking the setter methods are not defined. One can override this function to provide their own implementation for updating the device. The shadow update containing the delta (between the 'desired' state and the 'reported' state) is passed in as an input argument.
        Overrides:
        onShadowUpdate in class AbstractAwsIotDevice
        Parameters:
        jsonState - the JSON document containing the delta between 'desired' and 'reported' states

      • onDeviceReport

        public String onDeviceReport()
        This function handles collecting device data for reporting to the shadow. By default, it invokes the getter methods provided for the annotated device attributes. The data is serialized in a JSON document and reported to the shadow. One could override this default implementation and provide their own JSON document for reporting.
        Overrides:
        onDeviceReport in class AbstractAwsIotDevice
        Returns:
        the JSON document containing 'reported' state