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
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) This method updates desired properties for the specified device.
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

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.

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

public void updateDesiredProperties(DeviceTwinDevice device)
                             throws IotHubException,
                                    IOException

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:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

replaceDesiredProperties

public void replaceDesiredProperties(DeviceTwinDevice device)
                              throws IotHubException,
                                     IOException

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:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

replaceTags

public void replaceTags(DeviceTwinDevice device)
                 throws IotHubException,
                        IOException

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:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

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

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

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