Package com.amazonaws.services.iot.client

Class AWSIotDevice

java.lang.Object
com.amazonaws.services.iot.client.shadow.AbstractAwsIotDevice
com.amazonaws.services.iot.client.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 Details

    • AWSIotDevice

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

  • Method Details

    • 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

    • setDeviceReportQos

      public void setDeviceReportQos(AWSIotQos deviceReportQos)
      Sets the MQTT QoS level for publishing the device report. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call.
      Overrides:
      setDeviceReportQos in class AbstractAwsIotDevice
      Parameters:
      deviceReportQos - the new 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

    • setShadowUpdateQos

      public void setShadowUpdateQos(AWSIotQos shadowUpdateQos)
      Sets the MQTT QoS level for subscribing to shadow updates. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call.
      Overrides:
      setShadowUpdateQos in class AbstractAwsIotDevice
      Parameters:
      shadowUpdateQos - the new 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.

    • setMethodQos

      public void setMethodQos(AWSIotQos methodQos)
      Sets the MQTT QoS level for sending shadow methods. This value must be set before the device is attached to a client via the AWSIotMqttClient.attach(AWSIotDevice) call.
      Overrides:
      setMethodQos in class AbstractAwsIotDevice
      Parameters:
      methodQos - the new 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