com.microsoft.azure.sdk.iot.service.jobs

Class JobClient

java.lang.Object

com.microsoft.azure.sdk.iot.service.jobs.JobClient

public class JobClient
extends Object

Use the JobClient to schedule and cancel jobs for a group of devices using IoT hub.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
JobResult	cancelJob(String jobId) Cancel a current jod on the IoTHub
static JobClient	createFromConnectionString(String connectionString) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use JobClient(String) instead since it does not declare this exception even though it constructs the same JobClient.
JobResult	getJob(String jobId) Get the current job on the iotHub.
JobResult	getNextJob(Query query) returns the next job result in response.
boolean	hasNextJob(Query query) returns the availability of next job result in response.
Query	queryDeviceJob(String sqlQuery) Query for device Job limited by default page size of 100 for response
Query	queryDeviceJob(String sqlQuery, Integer pageSize) Query for device Job
Query	queryJobResponse(JobType jobType, JobStatus jobStatus) Query the iot hub for a jobs response.
Query	queryJobResponse(JobType jobType, JobStatus jobStatus, Integer pageSize) Query the iot hub for a jobs response.
JobResult	scheduleDeviceMethod(String jobId, String queryCondition, String methodName, Long responseTimeoutInSeconds, Long connectTimeoutInSeconds, Object payload, Date startTimeUtc, long maxExecutionTimeInSeconds) Creates a new Job to invoke method on one or multiple devices
JobResult	scheduleUpdateTwin(String jobId, String queryCondition, DeviceTwinDevice updateTwin, Date startTimeUtc, long maxExecutionTimeInSeconds) Creates a new Job to update twin tags and desired properties on one or multiple devices

Methods inherited from class java.lang.Object

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

Constructor Detail

JobClient

public JobClient(String connectionString)

Constructor to create instance from connection string

Parameters:

connectionString - The iot hub connection string

JobClient

public JobClient(String connectionString,
                 JobClientOptions options)

Constructor to create instance from connection string

Parameters:

connectionString - The iot hub connection string

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

JobClient

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

Create a new JobClient 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.

JobClient

public JobClient(String hostName,
                 com.azure.core.credential.TokenCredential credential,
                 JobClientOptions options)

Create a new JobClient 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.

JobClient

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

Create a new JobClient 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.

JobClient

public JobClient(String hostName,
                 com.azure.core.credential.AzureSasCredential azureSasCredential,
                 JobClientOptions options)

Create a new JobClient 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.

JobClient

protected JobClient()

Method Detail

createFromConnectionString

@Deprecated
public static JobClient createFromConnectionString(String connectionString)
                                                         throws IOException,
                                                                IllegalArgumentException

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

Static constructor to create instance from connection string

Parameters:

connectionString - The iot hub connection string

Returns:

The instance of JobClient

Throws:

IOException - This exception is never thrown.

IllegalArgumentException - if the provided connectionString is null or empty

scheduleUpdateTwin

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

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

Parameters:

jobId - Unique Job Id for this job

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 jobResult object

Throws:

IllegalArgumentException - if one of the provided parameters is invalid

IOException - if the function cannot create a URL for the job

IotHubException - if the http request failed

scheduleDeviceMethod

public JobResult scheduleDeviceMethod(String jobId,
                                      String queryCondition,
                                      String methodName,
                                      Long responseTimeoutInSeconds,
                                      Long connectTimeoutInSeconds,
                                      Object payload,
                                      Date startTimeUtc,
                                      long maxExecutionTimeInSeconds)
                               throws IllegalArgumentException,
                                      IOException,
                                      IotHubException

Creates a new Job to invoke method on one or multiple devices

Parameters:

jobId - Unique Job Id for this job

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

methodName - Method name to be invoked

responseTimeoutInSeconds - Maximum interval of time, in seconds, that the Direct Method will wait for answer. It can be null.

connectTimeoutInSeconds - Maximum interval of time, in seconds, that the Direct Method will wait for the connection. It can be null.

payload - Object that contains the payload defined by the user. It can be null.

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 jobResult object

Throws:

IllegalArgumentException - if one of the provided parameters is invalid

IOException - if the function cannot create a URL for the job, or the IO failed on request

IotHubException - if the http request failed

getJob

public JobResult getJob(String jobId)
                 throws IllegalArgumentException,
                        IOException,
                        IotHubException

Get the current job on the iotHub.

Parameters:

jobId - Unique Job Id for this job

Returns:

a jobResult object

Throws:

IllegalArgumentException - if the jobId is invalid

IOException - if the function cannot create a URL for the job, or the IO failed on request

IotHubException - if the http request failed

cancelJob

public JobResult cancelJob(String jobId)
                    throws IllegalArgumentException,
                           IOException,
                           IotHubException

Cancel a current jod on the IoTHub

Parameters:

jobId - Unique Job Id for this job

Returns:

a jobResult object

Throws:

IllegalArgumentException - if the jobId is invalid

IOException - if the function cannot create a URL for the job, or the IO failed on request

IotHubException - if the http request failed

queryDeviceJob

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

Query for device Job

Parameters:

sqlQuery - sql style query over device.jobs

pageSize - the value per which to limit the size of query response by.

Returns:

Query object for this query

Throws:

IotHubException - When IotHub fails to respond

IOException - When any of the parameters are incorrect

queryDeviceJob

public Query queryDeviceJob(String sqlQuery)
                     throws IotHubException,
                            IOException

Query for device Job limited by default page size of 100 for response

Parameters:

sqlQuery - sql style query over device.jobs

Returns:

Query object for this query

Throws:

IotHubException - When IotHub fails to respond

IOException - When any of the parameters are incorrect

hasNextJob

public boolean hasNextJob(Query query)
                   throws IotHubException,
                          IOException

returns the availability of next job result in response. Query's further if page size has been met

Parameters:

query - Query for which to look for next job response by

Returns:

true if next job result is available , false otherwise

Throws:

IotHubException - When IotHub fails to respond

IOException - if any of the input parameters are incorrect

getNextJob

public JobResult getNextJob(Query query)
                     throws IOException,
                            IotHubException,
                            NoSuchElementException

returns the next job result in response. Query's further if page size has been met and has next is not called

Parameters:

query - Query for which to look for next job response by

Returns:

next job result if available

Throws:

IotHubException - When IotHub fails to respond

IOException - if any of the input parameters are incorrect

NoSuchElementException - if called when no further responses are left

queryJobResponse

public Query queryJobResponse(JobType jobType,
                              JobStatus jobStatus,
                              Integer pageSize)
                       throws IOException,
                              IotHubException

Query the iot hub for a jobs response. Query response are limited by page size per attempt

Parameters:

jobType - The type of job to query for

jobStatus - The status of the job to query for

pageSize - The value to which to limit the job response size by

Returns:

A query object on which to look for responses by

Throws:

IOException - If any of the input parameters are incorrect

IotHubException - If IotHub failed to respond

queryJobResponse

public Query queryJobResponse(JobType jobType,
                              JobStatus jobStatus)
                       throws IotHubException,
                              IOException

Query the iot hub for a jobs response. Query response are limited by default page size per attempt

Parameters:

jobType - The type of job to query for

jobStatus - The status of the job to query for

Returns:

A query object on which to look for responses by

Throws:

IOException - If any of the input parameters are incorrect

IotHubException - If IotHub failed to respond