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

Constructor Summary

Constructors

Constructor and Description
DeviceTwin()

Method Summary

Modifier and Type	Method and Description
static DeviceTwin	createFromConnectionString(String connectionString) Static constructor to create instance from connection string.
static DeviceTwin	createFromConnectionString(String connectionString, DeviceTwinClientOptions options) Static constructor to create instance from connection string.
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 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.
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() 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()

Method Detail

createFromConnectionString

public static DeviceTwin createFromConnectionString(String connectionString)
                                             throws IOException

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 thrown if the object creation failed.

createFromConnectionString

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

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 thrown if the object creation failed.

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() 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 setDesiredProperties 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 setTags method.

Parameters:

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

Throws:

UnsupportedOperationException - This exception is always thrown.

queryTwin

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

Sql style query for twin.

Parameters:

sqlQuery - Sql query string to query IotHub 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 IotHub.

IOException - If input parameters are invalid.

queryTwin

public Query queryTwin(String sqlQuery)
                throws IotHubException,
                       IOException

Sql style query for twin.

Parameters:

sqlQuery - Sql query string to query IotHub 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 IotHub.

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 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 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 - Query object returned upon creation of query.

Returns:

True if next is available and false other wise.

Throws:

IotHubException - If IotHub 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 - Object corresponding to the query in request.

Returns:

Returns the next device twin document.

Throws:

IOException - If input parameter is incorrect.

IotHubException - If a non successful response from IotHub is received.

NoSuchElementException - If no additional element was found.

hasNext

public boolean hasNext(QueryCollection deviceTwinQueryCollection)

Returns 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 don'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 don'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 time in Utc to start the job.

maxExecutionTimeInSeconds - Max execution time in seconds, i.e., ttl duration the job can run.

Returns:

a Job class that represent this job on IotHub.

Throws:

IOException - if the function contains invalid parameters.

IotHubException - if the http request failed.