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

Class MessageFeedbackProcessorClient

java.lang.Object

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

public class MessageFeedbackProcessorClient
extends Object

A client for handling cloud to device message feedback. For more details on what cloud to device message feedback is, 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 MessageFeedbackProcessorClientOptions when constructing this client in order to monitor the connection state and to re-open the connection when needed. See the message feedback processor client sample in this repo for best practices for monitoring and handling disconnection events.

Constructor Summary

Constructors

Constructor and Description
MessageFeedbackProcessorClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor) Construct a MessageFeedbackProcessorClient using a AzureSasCredential instance for authentication.
MessageFeedbackProcessorClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor, MessageFeedbackProcessorClientOptions options) Construct a MessageFeedbackProcessorClient using a AzureSasCredential instance for authentication.
MessageFeedbackProcessorClient(String connectionString, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor) Construct a MessageFeedbackProcessorClient from the provided connection string.
MessageFeedbackProcessorClient(String connectionString, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor, MessageFeedbackProcessorClientOptions options) Construct a MessageFeedbackProcessorClient from the provided connection string.
MessageFeedbackProcessorClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor) Construct a MessageFeedbackProcessorClient using a TokenCredential instance for authentication.
MessageFeedbackProcessorClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol, Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor, MessageFeedbackProcessorClientOptions options) Construct a MessageFeedbackProcessorClient using a TokenCredential instance for authentication.

Method Summary

Modifier and Type	Method and Description
boolean	isRunning() Returns true if this client's underlying amqp connection is currently open and false otherwise.
void	start() Open this client so that it can begin processing message feedback.
void	start(int timeoutMilliseconds) Open this client so that it can begin processing message feedback.
void	stop() Stops this client from processing any more message feedback and releases all network resources tied to it.
void	stop(int timeoutMilliseconds) Stops this client from processing any more message feedback and releases all network resources tied to it.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String hostName,
                                      com.azure.core.credential.TokenCredential credential,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor)

Construct a MessageFeedbackProcessorClient using a TokenCredential instance for authentication.

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.

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String hostName,
                                      com.azure.core.credential.TokenCredential credential,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor,
                                      MessageFeedbackProcessorClientOptions options)

Construct a MessageFeedbackProcessorClient using a TokenCredential instance for authentication.

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.

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

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

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String hostName,
                                      com.azure.core.credential.AzureSasCredential azureSasCredential,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor)

Construct a MessageFeedbackProcessorClient using a AzureSasCredential instance for authentication.

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.

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String hostName,
                                      com.azure.core.credential.AzureSasCredential azureSasCredential,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor,
                                      MessageFeedbackProcessorClientOptions options)

Construct a MessageFeedbackProcessorClient using a AzureSasCredential instance for authentication.

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.

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

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

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String connectionString,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor)

Construct a MessageFeedbackProcessorClient from the provided connection string.

Parameters:

connectionString - The connection string for the Iot Hub.

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

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

MessageFeedbackProcessorClient

public MessageFeedbackProcessorClient(String connectionString,
                                      IotHubServiceClientProtocol protocol,
                                      Function<FeedbackBatch,AcknowledgementType> feedbackMessageProcessor,
                                      MessageFeedbackProcessorClientOptions options)

Construct a MessageFeedbackProcessorClient from the provided connection string.

Parameters:

connectionString - The connection string for the Iot Hub.

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

feedbackMessageProcessor - The callback to be executed each time message feedback is received from the service. May not be null.

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

Method Detail

start

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

Open this client so that it can begin processing message feedback. When you want to stop processing message feedback, you should should call stop() to free up network resources. If this client is already started, 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.

start

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

Open this client so that it can begin processing message feedback. When you want to stop processing message feedback, you should should call stop() to free up network resources. If this client is already started, 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.

stop

public void stop()
          throws InterruptedException

Stops this client from processing any more message feedback and releases all network resources tied to it. Once stopped, this client can be restarted by calling start(). 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.

stop

public void stop(int timeoutMilliseconds)
          throws InterruptedException

Stops this client from processing any more message feedback and releases all network resources tied to it. Once stopped, this client can be restarted by calling start(). If this client has already been stopped, 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.

isRunning

public boolean isRunning()

Returns true if this client's underlying amqp connection 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 MessageFeedbackProcessorClientOptions 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.