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.

Field Summary

Fields inherited from class com.amazonaws.services.iot.client.shadow.AbstractAwsIotDevice

deviceReportQos, enableVersioning, methodAckQos, methodQos, reportInterval, shadowUpdateQos, thingName

Constructor Summary

Constructors

Constructor and Description
AWSIotDevice(String thingName) Instantiates a new device instance.

Method Summary

Modifier and Type	Method and Description
void	delete() Deletes the content of a thing shadow.
void	delete(AWSIotMessage message, long timeout) Deletes the content of a thing shadow.
void	delete(long timeout) Deletes the content of a thing shadow.
String	get() Retrieves the latest state stored in the thing shadow.
void	get(AWSIotMessage message, long timeout) Retrieves the latest state stored in the thing shadow.
String	get(long timeout) Retrieves the latest state stored in the thing shadow.
AWSIotQos	getDeviceReportQos() Gets the MQTT QoS level for publishing the device report.
AWSIotQos	getMethodAckQos() Gets the MQTT QoS level for subscribing to acknowledgement messages of shadow methods.
AWSIotQos	getMethodQos() Gets the MQTT QoS level for sending the shadow methods, namely Get, Update, and Delete.
long	getReportInterval() Gets the device report interval.
AWSIotQos	getShadowUpdateQos() Gets the MQTT QoS level for subscribing to shadow updates.
boolean	isEnableVersioning() Checks if versioning is enabled for device updates.
String	onDeviceReport() This function handles collecting device data for reporting to the shadow.
void	onShadowUpdate(String jsonState) This function handles update messages received from the shadow.
void	setDeviceReportQos(AWSIotQos deviceReportQos) Sets the MQTT QoS level for publishing the device report.
void	setEnableVersioning(boolean enableVersioning) Sets the device update versioning to be enabled or disabled.
void	setMethodAckQos(AWSIotQos methodAckQos) Sets the MQTT QoS level for subscribing to acknowledgement messages of shadow methods.
void	setMethodQos(AWSIotQos methodQos) Sets the MQTT QoS level for sending shadow methods.
void	setReportInterval(long reportInterval) Sets the device report interval in milliseconds.
void	setShadowUpdateQos(AWSIotQos shadowUpdateQos) Sets the MQTT QoS level for subscribing to shadow updates.
void	update(AWSIotMessage message, long timeout) Updates the content of a thing shadow with the data provided in the request.
void	update(String jsonState) Updates the content of a thing shadow with the data provided in the request.
void	update(String jsonState, long timeout) Updates the content of a thing shadow with the data provided in the request.

Methods inherited from class com.amazonaws.services.iot.client.shadow.AbstractAwsIotDevice

activate, deactivate, getClient, getCommandManager, getDevice, getDeviceSubscriptions, getJsonObjectMapper, getLocalVersion, getReportedProperties, getSyncTask, getThingName, getUpdatableProperties, isCommandReady, isTopicReady, onCommandAck, onSubscriptionAck, setClient, setLocalVersion, setSyncTask, startSync, startVersionSync, stopSync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

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