DeviceTwin Class

Package:

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

Maven Artifact:

com.microsoft.azure.sdk.iot:iot-service-client:1.30.0

• java.lang.Object
• • com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwin

public class DeviceTwin

Constructor Summary

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

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 connectionString, DeviceTwinClientOptions options) instead since it does not declare this exception even though it constructs the same DeviceTwin. Static constructor to create instance from connection string.
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 connectionString, DeviceTwinClientOptions options) instead since it does not declare this exception even though it constructs the same DeviceTwin. Static constructor to create instance from connection string.
synchronized DeviceTwinDevice	getNextDeviceTwin(Query deviceTwinQuery) Returns the next device twin document.
void	getTwin(DeviceTwinDevice device) This method retrieves device twin for the specified device.
synchronized boolean	hasNext(QueryCollection deviceTwinQueryCollection) Returns True if the provided deviceTwinQueryCollection has a next page to query.
synchronized boolean	hasNextDeviceTwin(Query deviceTwinQuery) Returns the availability of next twin element upon query.
synchronized QueryCollectionResponse<DeviceTwinDevice>	next(QueryCollection deviceTwinQueryCollection) Returns the next DeviceTwinDevice collection for the given query alongside the continuation token needed for querying the next page.
synchronized 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.
synchronized Query	queryTwin(String sqlQuery) SQL-style query for twin.
synchronized Query	queryTwin(String sqlQuery, Integer pageSize) SQL-style query for twin.
synchronized QueryCollection	queryTwinCollection(String sqlQuery) Create a QueryCollection object that can be used to query whole pages of results at a time.
synchronized 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. This method updates desired properties for the specified device.
synchronized void	updateTwin(DeviceTwinDevice device) This method updates device twin for the specified device.

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

DeviceTwin

public DeviceTwin(String connectionString)

Constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

DeviceTwin

public DeviceTwin(String hostName, 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, 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.

DeviceTwin

public DeviceTwin(String hostName, 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, 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 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.

Method Details

createFromConnectionString

public 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 connectionString, DeviceTwinClientOptions options) 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:

java.io.IOException - This exception is never thrown.

createFromConnectionString

public 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 connectionString, DeviceTwinClientOptions options) 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:

java.io.IOException - This exception is never thrown.

getNextDeviceTwin

public synchronized DeviceTwinDevice getNextDeviceTwin(Query deviceTwinQuery)

Returns the next device twin document.

Parameters:

deviceTwinQuery - The object corresponding to the query in request.

Returns:

Returns the next device twin document.

Throws:

java.io.IOException - If the input parameter is incorrect.

IotHubException - If the input parameter is incorrect.

java.util.NoSuchElementException - If the input parameter is incorrect.

getTwin

public void getTwin(DeviceTwinDevice device)

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:

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

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

hasNext

public synchronized 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.

hasNextDeviceTwin

public synchronized boolean hasNextDeviceTwin(Query deviceTwinQuery)

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.

java.io.IOException - If Iot hub could not respond back to the query successfully.

next

public synchronized QueryCollectionResponse next(QueryCollection deviceTwinQueryCollection)

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:

java.io.IOException - If an IotHubException occurs when querying the service.

IotHubException - If an IotHubException occurs when querying the service.

next

public synchronized QueryCollectionResponse next(QueryCollection deviceTwinQueryCollection, QueryOptions options)

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:

java.io.IOException - If an IotHubException occurs when querying the service.

IotHubException - If an IotHubException occurs when querying the service.

queryTwin

public synchronized Query queryTwin(String sqlQuery)

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.

java.io.IOException - If query request was not successful at the Iot hub.

queryTwin

public synchronized Query queryTwin(String sqlQuery, Integer pageSize)

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.

java.io.IOException - If query request was not successful at the Iot hub.

queryTwinCollection

public synchronized QueryCollection queryTwinCollection(String sqlQuery)

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:

java.net.MalformedURLException - If twin query URL is not correct.

queryTwinCollection

public synchronized QueryCollection queryTwinCollection(String sqlQuery, Integer pageSize)

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:

java.net.MalformedURLException - If twin query URL is not correct.

replaceDesiredProperties

public void replaceDesiredProperties(DeviceTwinDevice device)

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

Parameters:

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

Throws:

java.lang.UnsupportedOperationException - This exception is always thrown.

replaceTags

public void replaceTags(DeviceTwinDevice device)

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

Parameters:

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

Throws:

java.lang.UnsupportedOperationException - This exception is always thrown.

replaceTwin

public DeviceTwinDevice replaceTwin(DeviceTwinDevice device)

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.

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

scheduleUpdateTwin

public 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.

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:

java.io.IOException - If the function contains invalid parameters.

IotHubException - If the function contains invalid parameters.

updateDesiredProperties

public void updateDesiredProperties(DeviceTwinDevice device)

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:

java.lang.UnsupportedOperationException - This exception is always thrown.

updateTwin

public synchronized void updateTwin(DeviceTwinDevice device)

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:

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

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