com.microsoft.azure.sdk.iot.service.messaging

Class MessagingClient

java.lang.Object

com.microsoft.azure.sdk.iot.service.messaging.MessagingClient

public final class MessagingClient
extends Object

A client for sending cloud to device and cloud to module messages. For more details on what cloud to device messages are, see this document.

This client relies on a persistent amqp/amqp_ws connection to IoT Hub that may break due to network instability. While optional to monitor, users are highly encouraged to utilize the errorProcessorHandler defined in the MessagingClientOptions when constructing this client in order to monitor the connection state and to re-open the connection when needed. See the messaging client sample in this repo for best practices for monitoring and handling disconnection events.

Constructor Summary

Constructors

Constructor and Description
MessagingClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol) Create a MessagingClient instance with an instance of AzureSasCredential.
MessagingClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol, MessagingClientOptions options) Create a MessagingClient instance with an instance of AzureSasCredential.
MessagingClient(String connectionString, IotHubServiceClientProtocol protocol) Construct a MessagingClient from the specified connection string
MessagingClient(String connectionString, IotHubServiceClientProtocol protocol, MessagingClientOptions options) Construct a MessagingClient from the specified connection string
MessagingClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol) Create a MessagingClient instance with a custom TokenCredential to allow for finer grain control of authentication tokens used in the underlying connection.
MessagingClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol, MessagingClientOptions options) Create a MessagingClient 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 this client and release all network resources tied to it.
void	close(int timeoutMilliseconds) Close this client and release all network resources tied to it.
boolean	isOpen() Returns true if this client is currently open and false otherwise.
void	open() Open this client so that it can begin sending cloud to device and/or cloud to module messages.
void	open(int timeoutMilliseconds) Open this client so that it can begin sending cloud to device and/or cloud to module messages.
void	send(String deviceId, Message message) Send a cloud to device message to the device with the provided device id.
void	send(String deviceId, Message message, int timeoutMilliseconds) Send a cloud to device message to the device with the provided device id.
void	send(String deviceId, String moduleId, Message message) Send a cloud to device message to the module with the provided module id on the device with the provided device Id.
void	send(String deviceId, String moduleId, Message message, int timeoutMilliseconds) Send a cloud to device message to the module with the provided module id on the device with the provided device Id.
void	sendAsync(String deviceId, Message message, Consumer<SendResult> onMessageSentCallback, Object context) Asynchronously send a cloud to device message to the device with the provided device Id.
void	sendAsync(String deviceId, String moduleId, Message message, Consumer<SendResult> onMessageSentCallback, Object context) Asynchronously send a cloud to device message to the module with the provided module id on the device with the provided device Id.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessagingClient

public MessagingClient(String connectionString,
                       IotHubServiceClientProtocol protocol)

Construct a MessagingClient from the specified connection string

Parameters:

connectionString - The connection string for the IotHub

protocol - The protocol that the client will communicate to IoT Hub over.

MessagingClient

public MessagingClient(String connectionString,
                       IotHubServiceClientProtocol protocol,
                       MessagingClientOptions options)

Construct a MessagingClient from the specified connection string

Parameters:

connectionString - The connection string for the IotHub

protocol - The protocol that the client will communicate to IoT Hub over.

options - The connection options to use when connecting to the service. May not be null.

MessagingClient

public MessagingClient(String hostName,
                       com.azure.core.credential.TokenCredential credential,
                       IotHubServiceClientProtocol protocol)

Create a MessagingClient 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.

protocol - The protocol that the client will communicate to IoT Hub over.

MessagingClient

public MessagingClient(String hostName,
                       com.azure.core.credential.TokenCredential credential,
                       IotHubServiceClientProtocol protocol,
                       MessagingClientOptions options)

Create a MessagingClient 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.

protocol - The protocol that the client will communicate to IoT Hub over.

options - The connection options to use when connecting to the service. May not be null.

MessagingClient

public MessagingClient(String hostName,
                       com.azure.core.credential.AzureSasCredential azureSasCredential,
                       IotHubServiceClientProtocol protocol)

Create a MessagingClient 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.

protocol - The protocol that the client will communicate to IoT Hub over.

MessagingClient

public MessagingClient(String hostName,
                       com.azure.core.credential.AzureSasCredential azureSasCredential,
                       IotHubServiceClientProtocol protocol,
                       MessagingClientOptions options)

Create a MessagingClient 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.

protocol - The protocol that the client will communicate to IoT Hub over.

options - The connection options to use when connecting to the service. May not be null.

Method Detail

open

public void open()
          throws IotHubException,
                 IOException,
                 InterruptedException,
                 TimeoutException

Open this client so that it can begin sending cloud to device and/or cloud to module messages. Once opened, you should call close() once no more messages will be sent in order to free up network resources. If this client is already open, then this function will do nothing.

Throws:

IotHubException - If any IoT Hub level exceptions occur such as an IotHubUnauthorizedException.

IOException - If any network level exceptions occur such as the connection timing out.

InterruptedException - If this thread is interrupted while waiting for the connection to the service to open.

TimeoutException - If the connection is not established before the default timeout.

open

public void open(int timeoutMilliseconds)
          throws IotHubException,
                 IOException,
                 InterruptedException,
                 TimeoutException

Open this client so that it can begin sending cloud to device and/or cloud to module messages. Once opened, this client should call close() once no more messages will be sent in order to free up network resources. If this client is already open, then this function will do nothing.

Parameters:

timeoutMilliseconds - the maximum number of milliseconds to wait for the underlying amqp connection to open. If this value is 0, it will have an infinite timeout.

Throws:

IotHubException - If any IoT Hub level exceptions occur such as an IotHubUnauthorizedException.

IOException - If any network level exceptions occur such as the connection timing out.

InterruptedException - If this thread is interrupted while waiting for the connection to the service to open.

TimeoutException - If the connection is not established before the provided timeout.

close

public void close()
           throws InterruptedException

Close this client and release all network resources tied to it. Once closed, this client can be re-opened by calling open(). If this client is already closed, this function will do nothing.

Throws:

InterruptedException - if this function is interrupted while waiting for the connection to close down all network resources.

close

public void close(int timeoutMilliseconds)
           throws InterruptedException

Close this client and release all network resources tied to it. Once closed, this client can be re-opened by calling open(). If this client is already closed, this function will do nothing.

Parameters:

timeoutMilliseconds - the maximum number of milliseconds to wait for the underlying amqp connection to close. If this value is 0, it will have an infinite timeout. If the provided timeout has passed and the connection has not closed gracefully, then the connection will be forcefully closed and no exception will be thrown.

Throws:

InterruptedException - if this function is interrupted while waiting for the connection to close down all network resources.

send

public void send(String deviceId,
                 Message message)
          throws IotHubException,
                 InterruptedException,
                 TimeoutException,
                 IllegalStateException

Send a cloud to device message to the device with the provided device id.

This method is a blocking call that will wait for the sent message to be acknowledged by the service before returning. This is provided for simplicity and for applications that aren't concerned with throughput. For applications that need to provided higher throughput of sent cloud to device messages, users should use sendAsync(String, Message, Consumer, Object) as demonstrated in the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device to send the cloud to device message to.

message - the message to send to the device.

Throws:

IotHubException - If any IoT Hub level exception is thrown. For instance, if the provided message exceeds the IoT Hub message size limit, IotHubMessageTooLargeException will be thrown.

InterruptedException - If this function is interrupted while waiting for the cloud to device message to be acknowledged by the service.

TimeoutException - If the sent message isn't acknowledged by the service within the default timeout.

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

send

public void send(String deviceId,
                 Message message,
                 int timeoutMilliseconds)
          throws IotHubException,
                 InterruptedException,
                 TimeoutException,
                 IllegalStateException

Send a cloud to device message to the device with the provided device id.

This method is a blocking call that will wait for the sent message to be acknowledged by the service before returning. This is provided for simplicity and for applications that aren't concerned with throughput. For applications that need to provided higher throughput of sent cloud to device messages, users should use sendAsync(String, Message, Consumer, Object) as demonstrated in the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device to send the cloud to device message to.

message - the message to send to the device.

timeoutMilliseconds - the maximum number of milliseconds to wait for the message to be sent before timing out and throwing an IotHubException.

Throws:

IotHubException - If any IoT Hub level exception is thrown. For instance, if the provided message exceeds the IoT Hub message size limit, IotHubMessageTooLargeException will be thrown.

InterruptedException - If this function is interrupted while waiting for the cloud to device message to be acknowledged by the service.

TimeoutException - If the sent message isn't acknowledged by the service within the provided timeout.

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

send

public void send(String deviceId,
                 String moduleId,
                 Message message)
          throws IotHubException,
                 InterruptedException,
                 TimeoutException,
                 IllegalStateException

Send a cloud to device message to the module with the provided module id on the device with the provided device Id.

This method is a blocking call that will wait for the sent message to be acknowledged by the service before returning. This is provided for simplicity and for applications that aren't concerned with throughput. For applications that need to provided higher throughput of sent cloud to device messages, users should use sendAsync(String, String, Message, Consumer, Object) as demonstrated in the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device that contains the module that the message is being sent to.

moduleId - the Id of the module to send the cloud to device message to.

message - the message to send to the device.

Throws:

IotHubException - If any IoT Hub level exception is thrown. For instance, if the provided message exceeds the IoT Hub message size limit, IotHubMessageTooLargeException will be thrown.

InterruptedException - If this function is interrupted while waiting for the cloud to device message to be acknowledged by the service.

TimeoutException - If the sent message isn't acknowledged by the service within the default timeout.

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

send

public void send(String deviceId,
                 String moduleId,
                 Message message,
                 int timeoutMilliseconds)
          throws IotHubException,
                 InterruptedException,
                 TimeoutException,
                 IllegalStateException

Send a cloud to device message to the module with the provided module id on the device with the provided device Id.

This method is a blocking call that will wait for the sent message to be acknowledged by the service before returning. This is provided for simplicity and for applications that aren't concerned with throughput. For applications that need to provided higher throughput of sent cloud to device messages, users should use sendAsync(String, String, Message, Consumer, Object) as demonstrated in the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device that contains the module that the message is being sent to.

moduleId - the Id of the module to send the cloud to device message to.

message - the message to send to the device.

timeoutMilliseconds - the maximum number of milliseconds to wait for the message to be sent before timing out and throwing an IotHubException.

Throws:

IotHubException - If any IoT Hub level exception is thrown. For instance, if the provided message exceeds the IoT Hub message size limit, IotHubMessageTooLargeException will be thrown.

InterruptedException - If this function is interrupted while waiting for the cloud to device message to be acknowledged by the service.

TimeoutException - If the sent message isn't acknowledged by the service within the provided timeout.

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

sendAsync

public void sendAsync(String deviceId,
                      Message message,
                      Consumer<SendResult> onMessageSentCallback,
                      Object context)
               throws IllegalStateException

Asynchronously send a cloud to device message to the device with the provided device Id.

Unlike the synchronous version of this function, this function does not throw any exceptions. Instead, any exception encountered while sending the message will be provided in the SendResult provided in the onMessageSentCallback. To see an example of how this looks, see the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device to send the cloud to device message to.

message - the message to send to the device.

onMessageSentCallback - the callback that will be executed when the message has either successfully been sent, or has failed to send. May be null if you don't care if the sent message is acknowledged by the service.

context - user defined context that will be provided in the onMessageSentCallback callback when it executes. May be null.

Throws:

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

sendAsync

public void sendAsync(String deviceId,
                      String moduleId,
                      Message message,
                      Consumer<SendResult> onMessageSentCallback,
                      Object context)
               throws IllegalStateException

Asynchronously send a cloud to device message to the module with the provided module id on the device with the provided device Id.

Unlike the synchronous version of this function, this function does not throw any exceptions. Instead, any exception encountered while sending the message will be provided in the SendResult provided in the onMessageSentCallback. To see an example of how this looks, see the messaging client performance sample in this repo.

Parameters:

deviceId - the Id of the device that contains the module that the message is being sent to.

moduleId - the Id of the module to send the cloud to device message to.

message - the message to send to the device.

onMessageSentCallback - the callback that will be executed when the message has either successfully been sent, or has failed to send. May be null if you don't care if the sent message is acknowledged by the service.

context - user defined context that will be provided in the onMessageSentCallback callback when it executes. May be null.

Throws:

IllegalStateException - if the client has not been opened yet, or is closed for any other reason such as connectivity loss.

isOpen

public boolean isOpen()

Returns true if this client is currently open and false otherwise. This client may lose connectivity due to network issues, so this value may be false even if you have not closed the client yourself. Monitoring the optional errorProcessor that can be set in MessagingClientOptions will provide the context on when connection loss events occur, and why they occurred.

Returns:

true if this client is currently open and false otherwise.