com.microsoft.azure.sdk.iot.service.devicetwin

Class DeviceTwin

java.lang.Object

com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwin

public class DeviceTwin
extends Object

Use the DeviceTwin class to manage the device twins in IoT hubs.

Constructor Summary

Constructors

Constructor and Description
DeviceTwin(String connectionString) Constructor to create instance from connection string.
DeviceTwin(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential) Create a new DeviceTwin instance.
DeviceTwin(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, DeviceTwinClientOptions options) Create a new DeviceTwin instance.
DeviceTwin(String connectionString, DeviceTwinClientOptions options) Constructor to create instance from connection string.
DeviceTwin(String hostName, com.azure.core.credential.TokenCredential credential) Create a new DeviceTwin instance.
DeviceTwin(String hostName, com.azure.core.credential.TokenCredential credential, DeviceTwinClientOptions options) Create a new DeviceTwin instance.

Method Summary

Modifier and Type	Method and Description
static DeviceTwin	createFromConnectionString(String connectionString) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceTwin(String, DeviceTwinClientOptions) instead since it does not declare this exception even though it constructs the same DeviceTwin.
static DeviceTwin	createFromConnectionString(String connectionString, DeviceTwinClientOptions options) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceTwin(String, DeviceTwinClientOptions) instead since it does not declare this exception even though it constructs the same DeviceTwin.
DeviceTwinDevice	getNextDeviceTwin(Query deviceTwinQuery) Returns the next device twin document.
void	getTwin(DeviceTwinDevice device) This method retrieves device twin for the specified device.
boolean	hasNext(QueryCollection deviceTwinQueryCollection) Returns True if the provided deviceTwinQueryCollection has a next page to query.
boolean	hasNextDeviceTwin(Query deviceTwinQuery) Returns the availability of next twin element upon query.
QueryCollectionResponse<DeviceTwinDevice>	next(QueryCollection deviceTwinQueryCollection) Returns the next DeviceTwinDevice collection for the given query alongside the continuation token needed for querying the next page.
QueryCollectionResponse<DeviceTwinDevice>	next(QueryCollection deviceTwinQueryCollection, QueryOptions options) Returns the next DeviceTwinDevice collection for the given query alongside the continuation token needed for querying the next page.
Query	queryTwin(String sqlQuery) SQL-style query for twin.
Query	queryTwin(String sqlQuery, Integer pageSize) SQL-style query for twin.
QueryCollection	queryTwinCollection(String sqlQuery) Create a QueryCollection object that can be used to query whole pages of results at a time.
QueryCollection	queryTwinCollection(String sqlQuery, Integer pageSize) Create a QueryCollection object that can be used to query whole pages of results at a time.
void	replaceDesiredProperties(DeviceTwinDevice device) This method replaces desired properties for the specified device.
void	replaceTags(DeviceTwinDevice device) This method replaces tags for the specified device.
DeviceTwinDevice	replaceTwin(DeviceTwinDevice device) Replace the full device twin for a given device with the provided device twin.
Job	scheduleUpdateTwin(String queryCondition, DeviceTwinDevice updateTwin, Date startTimeUtc, long maxExecutionTimeInSeconds) Creates a new Job to update twin tags and desired properties on one or multiple devices.
void	updateDesiredProperties(DeviceTwinDevice device) Deprecated. Use updateTwin(DeviceTwinDevice device) to update desired properties.
void	updateTwin(DeviceTwinDevice device) This method updates device twin for the specified device.

Methods inherited from class java.lang.Object

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

Constructor Detail

DeviceTwin

public DeviceTwin(String connectionString)

Constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

DeviceTwin

public DeviceTwin(String connectionString,
                  DeviceTwinClientOptions options)

Constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

options - the configurable options for each operation on this client. May not be null.

DeviceTwin

public DeviceTwin(String hostName,
                  com.azure.core.credential.TokenCredential credential)

Create a new DeviceTwin instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

DeviceTwin

public DeviceTwin(String hostName,
                  com.azure.core.credential.TokenCredential credential,
                  DeviceTwinClientOptions options)

Create a new DeviceTwin instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

options - The connection options to use when connecting to the service.

DeviceTwin

public DeviceTwin(String hostName,
                  com.azure.core.credential.AzureSasCredential azureSasCredential)

Create a new DeviceTwin instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

DeviceTwin

public DeviceTwin(String hostName,
                  com.azure.core.credential.AzureSasCredential azureSasCredential,
                  DeviceTwinClientOptions options)

Create a new DeviceTwin instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

options - The connection options to use when connecting to the service.

Method Detail

createFromConnectionString

@Deprecated
public static DeviceTwin createFromConnectionString(String connectionString)
                                                          throws IOException

Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceTwin(String, DeviceTwinClientOptions) instead since it does not declare this exception even though it constructs the same DeviceTwin.

Static constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

Returns:

The instance of DeviceTwin.

Throws:

IOException - This exception is never thrown.

createFromConnectionString

@Deprecated
public static DeviceTwin createFromConnectionString(String connectionString,
                                                                 DeviceTwinClientOptions options)
                                                          throws IOException

Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use DeviceTwin(String, DeviceTwinClientOptions) instead since it does not declare this exception even though it constructs the same DeviceTwin.

Static constructor to create instance from connection string.

Parameters:

connectionString - The IoT hub connection string.

options - The configurable options for each operation on this client. May not be null.

Returns:

The instance of DeviceTwin.

Throws:

IOException - This exception is never thrown.

getTwin

public void getTwin(DeviceTwinDevice device)
             throws IotHubException,
                    IOException

This method retrieves device twin for the specified device.

Parameters:

device - The device with a valid id for which device twin is to be retrieved.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

updateTwin

public void updateTwin(DeviceTwinDevice device)
                throws IotHubException,
                       IOException

This method updates device twin for the specified device.

This API uses the IoT Hub PATCH API when sending updates, but it sends the full twin with each patch update. As a result, devices subscribed to twin will receive notifications that each property is changed when this API is called, even if only some of the properties were changed.

See PATCH for more details.

Parameters:

device - The device with a valid Id for which device twin is to be updated.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

updateDesiredProperties

@Deprecated
public void updateDesiredProperties(DeviceTwinDevice device)
                                          throws UnsupportedOperationException

Deprecated. Use updateTwin(DeviceTwinDevice device) to update desired properties.

This method updates desired properties for the specified device.

Parameters:

device - The device with a valid id for which desired properties is to be updated.

Throws:

UnsupportedOperationException - This exception is always thrown.

replaceDesiredProperties

public void replaceDesiredProperties(DeviceTwinDevice device)
                              throws UnsupportedOperationException

This method replaces desired properties for the specified device. desired properties can be input via device's DeviceTwinDevice.setDesiredProperties(TwinCollection) method.

Parameters:

device - The device with a valid id for which device twin is to be updated.

Throws:

UnsupportedOperationException - This exception is always thrown.

replaceTags

public void replaceTags(DeviceTwinDevice device)
                 throws UnsupportedOperationException

This method replaces tags for the specified device. Tags can be input via device's DeviceTwinDevice.setTags(TwinCollection) method.

Parameters:

device - The device with a valid Id for which device twin is to be updated.

Throws:

UnsupportedOperationException - This exception is always thrown.

replaceTwin

public DeviceTwinDevice replaceTwin(DeviceTwinDevice device)
                             throws IotHubException,
                                    IOException

Replace the full device twin for a given device with the provided device twin.

Parameters:

device - The device twin object to replace the current device twin object.

Returns:

The Twin object's current state returned from the service after the replace operation.

Throws:

IotHubException - If any an IoT hub level exception is thrown. For instance, if the request is unauthorized, a exception that extends IotHubException will be thrown.

IOException - If the request failed to send to IoT hub.

queryTwin

public Query queryTwin(String sqlQuery,
                       Integer pageSize)
                throws IotHubException,
                       IOException

SQL-style query for twin.

Parameters:

sqlQuery - SQL-style query string to query Iot hub for Twin.

pageSize - Size to limit query response by.

Returns:

Query Object to be used for looking up responses for this query.

Throws:

IotHubException - If query request was not successful at the Iot hub.

IOException - If input parameters are invalid.

queryTwin

public Query queryTwin(String sqlQuery)
                throws IotHubException,
                       IOException

SQL-style query for twin.

Parameters:

sqlQuery - SQL-style query string to query Iot hub for twin.

Returns:

Query Object to be used for looking up responses for this query.

Throws:

IotHubException - If query request was not successful at the Iot hub.

IOException - If input parameters are invalid.

queryTwinCollection

public QueryCollection queryTwinCollection(String sqlQuery)
                                    throws MalformedURLException

Create a QueryCollection object that can be used to query whole pages of results at a time. QueryCollection objects also allow you to provide a continuation token for the query to pick up from.

Parameters:

sqlQuery - The SQL-style query to run.

Returns:

The created QueryCollection object that can be used to query the service.

Throws:

MalformedURLException - If twin query URL is not correct.

queryTwinCollection

public QueryCollection queryTwinCollection(String sqlQuery,
                                           Integer pageSize)
                                    throws MalformedURLException

Create a QueryCollection object that can be used to query whole pages of results at a time. QueryCollection objects also allow you to provide a continuation token for the query to pick up from.

Parameters:

sqlQuery - The SQL-style query to run.

pageSize - the number of results to return at a time.

Returns:

The created QueryCollection object that can be used to query the service.

Throws:

MalformedURLException - If twin query URL is not correct.

hasNextDeviceTwin

public boolean hasNextDeviceTwin(Query deviceTwinQuery)
                          throws IotHubException,
                                 IOException

Returns the availability of next twin element upon query. If non was found, Query is sent over again and response is updated accordingly until no response for the query was found.

Parameters:

deviceTwinQuery - The Query object returned upon creation of query.

Returns:

True if next is available and false otherwise.

Throws:

IotHubException - If Iot hub could not respond back to the query successfully.

IOException - If input parameter is incorrect.

getNextDeviceTwin

public DeviceTwinDevice getNextDeviceTwin(Query deviceTwinQuery)
                                   throws IOException,
                                          IotHubException,
                                          NoSuchElementException

Returns the next device twin document.

Parameters:

deviceTwinQuery - The object corresponding to the query in request.

Returns:

Returns the next device twin document.

Throws:

IOException - If the input parameter is incorrect.

IotHubException - If an unsuccessful response from IoT Hub is received.

NoSuchElementException - If no additional element was found.

hasNext

public boolean hasNext(QueryCollection deviceTwinQueryCollection)

Returns True if the provided deviceTwinQueryCollection has a next page to query.

Parameters:

deviceTwinQueryCollection - The query to check.

Returns:

True if the provided deviceTwinQueryCollection has a next page to query, false otherwise.

Throws:

IllegalArgumentException - if the provided deviceTwinQueryCollection is null.

next

public QueryCollectionResponse<DeviceTwinDevice> next(QueryCollection deviceTwinQueryCollection)
                                               throws IOException,
                                                      IotHubException

Returns the next DeviceTwinDevice collection for the given query alongside the continuation token needed for querying the next page.

This function shall update a local continuation token continuously to continue the query so you don't need to re-supply the returned continuation token.

Parameters:

deviceTwinQueryCollection - The query to run.

Returns:

The page of query results and the continuation token for the next page of results. Return value shall be null if there is no next collection.

Throws:

IotHubException - If an IotHubException occurs when querying the service.

IOException - If an IotHubException occurs when querying the service or if the results of that query doesn't match expectations.

next

public QueryCollectionResponse<DeviceTwinDevice> next(QueryCollection deviceTwinQueryCollection,
                                                      QueryOptions options)
                                               throws IOException,
                                                      IotHubException

Returns the next DeviceTwinDevice collection for the given query alongside the continuation token needed for querying the next page.

This function shall update a local continuation token continuously to continue the query so you don't need to re-supply the returned continuation token unless you want to continue the query from a different starting point. To do that, set your new continuation token in the query options object.

The provided option's page size shall override any previously saved page size.

Parameters:

deviceTwinQueryCollection - The query to run.

options - The query options to run the query with. If the continuation token in these options is null, the internally saved continuation token shall be used. The page size set in the options will override any previously set page size.

Returns:

The page of query results and the continuation token for the next page of results. Return value shall be null if there is no next collection.

Throws:

IotHubException - If an IotHubException occurs when querying the service.

IOException - If an IotHubException occurs when querying the service or if the results of that query doesn't match expectations.

scheduleUpdateTwin

public Job scheduleUpdateTwin(String queryCondition,
                              DeviceTwinDevice updateTwin,
                              Date startTimeUtc,
                              long maxExecutionTimeInSeconds)
                       throws IOException,
                              IotHubException

Creates a new Job to update twin tags and desired properties on one or multiple devices.

Parameters:

queryCondition - Query condition to evaluate which devices to run the job on. It can be null or empty.

updateTwin - Twin object to use for the update.

startTimeUtc - Date and time in UTC to start the job.

maxExecutionTimeInSeconds - Max run time in seconds, I.E., the duration the job can run.

Returns:

A Job class that represent this job on IoT hub.

Throws:

IOException - If the function contains invalid parameters.

IotHubException - If the HTTP request failed.