MessagingClient Class

Package:

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

• java.lang.Object
• • com.microsoft.azure.sdk.iot.service.messaging.MessagingClient

public class MessagingClient

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

Constructor	Description
MessagingClient(String hostName, AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol)	Create a MessagingClient instance with an instance of AzureSasCredential.
MessagingClient(String hostName, 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, 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, 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
synchronized void	close() 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.
synchronized void	close(int timeoutMilliseconds) 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.
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.
synchronized void	open() 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.
synchronized void	open(int timeoutMilliseconds) 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.
void	send(String deviceId, Message message) 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.
void	send(String deviceId, Message message, int timeoutMilliseconds) 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.
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. 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.
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. 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.
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. 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.
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. 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.

Constructor Details

MessagingClient

public MessagingClient(String hostName, 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, 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.

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, 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, 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.

Method Details

close

public synchronized void close()

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 synchronized void close(int timeoutMilliseconds)

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.

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.

open

public synchronized void open()

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 synchronized void open(int timeoutMilliseconds)

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.

send

public void send(String deviceId, Message message)

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)

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)

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)

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 onMessageSentCallback, Object context)

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 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.

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.