com.microsoft.azure.sdk.iot.service

Class ServiceClient

java.lang.Object

com.microsoft.azure.sdk.iot.service.ServiceClient

public class ServiceClient
extends Object

Use the ServiceClient to send and monitor messages to devices in IoT hubs. It can also be used to know when files have been uploaded by devices.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ServiceClient(IotHubConnectionString iotHubConnectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol) Initialize AMQP sender using given connection string
protected	ServiceClient(IotHubConnectionString iotHubConnectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol, ServiceClientOptions options) Initialize AMQP sender using given connection string
	ServiceClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol iotHubServiceClientProtocol) Create a ServiceClient instance with an instance of AzureSasCredential.
	ServiceClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol iotHubServiceClientProtocol, ServiceClientOptions options) Create a ServiceClient instance with an instance of AzureSasCredential.
	ServiceClient(String connectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol) Create ServiceClient from the specified connection string
	ServiceClient(String connectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol, ServiceClientOptions options) Create ServiceClient from the specified connection string
	ServiceClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol iotHubServiceClientProtocol) Create a ServiceClient instance with a custom TokenCredential to allow for finer grain control of authentication tokens used in the underlying connection.
	ServiceClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol iotHubServiceClientProtocol, ServiceClientOptions options) Create a ServiceClient instance with a custom TokenCredential to allow for finer grain control of authentication tokens used in the underlying connection.

Method Summary

Modifier and Type	Method and Description
void	close() Close AMQP sender
CompletableFuture<Void>	closeAsync() Deprecated. Use the synchronous version of this API close(). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.
static ServiceClient	createFromConnectionString(String connectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use ServiceClient(String, IotHubServiceClientProtocol) instead since it does not declare this exception even though it constructs the same ServiceClient.
static ServiceClient	createFromConnectionString(String connectionString, IotHubServiceClientProtocol iotHubServiceClientProtocol, ServiceClientOptions options) Deprecated. because this method declares a thrown IOException even though it never throws an IOException. Users are recommended to use ServiceClient(String, IotHubServiceClientProtocol, ServiceClientOptions) instead since it does not declare this exception even though it constructs the same ServiceClient.
FeedbackReceiver	getFeedbackReceiver() Instantiate a new FeedbackReceiver object.
FeedbackReceiver	getFeedbackReceiver(String deviceId) Deprecated. As of release 1.1.15, replaced by getFeedbackReceiver()
FileUploadNotificationReceiver	getFileUploadNotificationReceiver() Instantiate a new FileUploadNotificationReceiver object.
void	open() Open AMQP sender
CompletableFuture<Void>	openAsync() Deprecated. Use the synchronous version of this API open(). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.
void	send(String deviceId, Message message) Send a one-way message to the specified device.
void	send(String deviceId, String moduleId, Message message) Send a one-way message to the specified module.
CompletableFuture<Void>	sendAsync(String deviceId, Message message) Deprecated. Use the synchronous version of this API send(String, Message). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServiceClient

public ServiceClient(String connectionString,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol)

Create ServiceClient from the specified connection string

Parameters:

iotHubServiceClientProtocol - protocol to use

connectionString - The connection string for the IotHub

ServiceClient

public ServiceClient(String connectionString,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol,
                     ServiceClientOptions options)

Create ServiceClient from the specified connection string

Parameters:

iotHubServiceClientProtocol - protocol to use

connectionString - The connection string for the IotHub

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

ServiceClient

public ServiceClient(String hostName,
                     com.azure.core.credential.TokenCredential credential,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol)

Create a ServiceClient instance with a custom TokenCredential to allow for finer grain control of authentication tokens used in the underlying connection.

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.

iotHubServiceClientProtocol - The protocol to open the connection with.

ServiceClient

public ServiceClient(String hostName,
                     com.azure.core.credential.TokenCredential credential,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol,
                     ServiceClientOptions options)

Create a ServiceClient instance with a custom TokenCredential to allow for finer grain control of authentication tokens used in the underlying connection.

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.

iotHubServiceClientProtocol - The protocol to open the connection with.

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

ServiceClient

public ServiceClient(String hostName,
                     com.azure.core.credential.AzureSasCredential azureSasCredential,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol)

Create a ServiceClient instance with an instance of AzureSasCredential.

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.

iotHubServiceClientProtocol - The protocol to open the connection with.

ServiceClient

public ServiceClient(String hostName,
                     com.azure.core.credential.AzureSasCredential azureSasCredential,
                     IotHubServiceClientProtocol iotHubServiceClientProtocol,
                     ServiceClientOptions options)

Create a ServiceClient instance with an instance of AzureSasCredential.

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.

iotHubServiceClientProtocol - The protocol to open the connection with.

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

ServiceClient

protected ServiceClient(IotHubConnectionString iotHubConnectionString,
                        IotHubServiceClientProtocol iotHubServiceClientProtocol)

Initialize AMQP sender using given connection string

Parameters:

iotHubConnectionString - The ConnectionString object for the IotHub

iotHubServiceClientProtocol - protocol to use

ServiceClient

protected ServiceClient(IotHubConnectionString iotHubConnectionString,
                        IotHubServiceClientProtocol iotHubServiceClientProtocol,
                        ServiceClientOptions options)

Initialize AMQP sender using given connection string

Parameters:

iotHubConnectionString - The ConnectionString object for the IotHub

iotHubServiceClientProtocol - protocol to use

options - options for proxy

Method Detail

createFromConnectionString

@Deprecated
public static ServiceClient createFromConnectionString(String connectionString,
                                                                    IotHubServiceClientProtocol iotHubServiceClientProtocol)
                                                             throws IOException

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

Create ServiceClient from the specified connection string

Parameters:

iotHubServiceClientProtocol - protocol to use

connectionString - The connection string for the IotHub

Returns:

The created ServiceClient object

Throws:

IOException - This exception is thrown if the object creation failed

createFromConnectionString

@Deprecated
public static ServiceClient createFromConnectionString(String connectionString,
                                                                    IotHubServiceClientProtocol iotHubServiceClientProtocol,
                                                                    ServiceClientOptions options)
                                                             throws IOException

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

Create ServiceClient from the specified connection string

Parameters:

iotHubServiceClientProtocol - protocol to use

connectionString - The connection string for the IotHub

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

Returns:

The created ServiceClient object

Throws:

IOException - This exception is thrown if the object creation failed

open

public void open()
          throws IOException

Open AMQP sender

Throws:

IOException - This exception is thrown if the AmqpSender object is not initialized

close

public void close()
           throws IOException

Close AMQP sender

Throws:

IOException - This exception is thrown if the AmqpSender object is not initialized

send

public void send(String deviceId,
                 Message message)
          throws IOException,
                 IotHubException

Send a one-way message to the specified device. This function is synchronized internally so that only one send operation is allowed at a time. In order to do more send operations at a time, you will need to instantiate another service client instance.

Parameters:

deviceId - The device identifier for the target device

message - The message for the device

Throws:

IOException - This exception is thrown if the AmqpSender object is not initialized

IotHubException - This exception is thrown if IotHub rejects the message for any reason

send

public void send(String deviceId,
                 String moduleId,
                 Message message)
          throws IOException,
                 IotHubException

Send a one-way message to the specified module. This function is synchronized internally so that only one send operation is allowed at a time. In order to do more send operations at a time, you will need to instantiate another service client instance.

Parameters:

deviceId - The device identifier for the target device

moduleId - The module identifier for the target device

message - The message for the device

Throws:

IOException - This exception is thrown if the AmqpSender object is not initialized

IotHubException - This exception is thrown if IotHub rejects the message for any reason

openAsync

@Deprecated
public CompletableFuture<Void> openAsync()

Deprecated. Use the synchronous version of this API open(). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.

Provide asynchronous access to open()

Returns:

The future object for the requested operation

closeAsync

@Deprecated
public CompletableFuture<Void> closeAsync()

Deprecated. Use the synchronous version of this API close(). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.

Provide asynchronous access to close()

Returns:

The future object for the requested operation

sendAsync

@Deprecated
public CompletableFuture<Void> sendAsync(String deviceId,
                                                      Message message)

Deprecated. Use the synchronous version of this API send(String, Message). This asynchronous API only spawned a thread to run the synchronous API, so users are advised to do this themselves in order to have control over the spawned threads.

Provide asynchronous access to send()

Parameters:

deviceId - The device identifier for the target device

message - The message for the device

Returns:

The future object for the requested operation

getFeedbackReceiver

@Deprecated
public FeedbackReceiver getFeedbackReceiver(String deviceId)

Deprecated. As of release 1.1.15, replaced by getFeedbackReceiver()

Get FeedbackReceiver object.This API has been deprecated. Use new API without deviceId as an input parameter.

Parameters:

deviceId - The device identifier for the target device

Returns:

The instance of the FeedbackReceiver

getFeedbackReceiver

public FeedbackReceiver getFeedbackReceiver()

Instantiate a new FeedbackReceiver object.

Returns:

The instance of the FeedbackReceiver

getFileUploadNotificationReceiver

public FileUploadNotificationReceiver getFileUploadNotificationReceiver()

Instantiate a new FileUploadNotificationReceiver object.

Returns:

The instance of the FileUploadNotificationReceiver