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

Class FileUploadNotificationProcessorClient

java.lang.Object

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

public class FileUploadNotificationProcessorClient
extends Object

A client for handling file upload notifications. For more details on what file upload notifications 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 FileUploadNotificationProcessorClientOptions 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
FileUploadNotificationProcessorClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor) Construct a FileUploadNotificationProcessorClient using a AzureSasCredential instance for authentication.
FileUploadNotificationProcessorClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor, FileUploadNotificationProcessorClientOptions options) Construct a FileUploadNotificationProcessorClient using a AzureSasCredential instance for authentication.
FileUploadNotificationProcessorClient(String connectionString, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor) Construct a FileUploadNotificationProcessorClient from the provided connection string.
FileUploadNotificationProcessorClient(String connectionString, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor, FileUploadNotificationProcessorClientOptions options) Construct a FileUploadNotificationProcessorClient from the provided connection string.
FileUploadNotificationProcessorClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor) Construct a FileUploadNotificationProcessorClient using a TokenCredential instance for authentication.
FileUploadNotificationProcessorClient(String hostName, com.azure.core.credential.TokenCredential credential, IotHubServiceClientProtocol protocol, Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor, FileUploadNotificationProcessorClientOptions options) Construct a FileUploadNotificationProcessorClient 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 file upload notifications.
void	start(int timeoutMilliseconds) Open this client so that it can begin processing file upload notifications.
void	stop() Stops this client from processing any more file upload notifications and releases all network resources tied to it.
void	stop(int timeoutMilliseconds) Stops this client from processing any more file upload notifications 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

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String hostName,
                                             com.azure.core.credential.TokenCredential credential,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification is received from the service. May not be null.

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String hostName,
                                             com.azure.core.credential.TokenCredential credential,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor,
                                             FileUploadNotificationProcessorClientOptions options)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification is received from the service. May not be null.

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

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String hostName,
                                             com.azure.core.credential.AzureSasCredential azureSasCredential,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification is received from the service. May not be null.

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String hostName,
                                             com.azure.core.credential.AzureSasCredential azureSasCredential,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor,
                                             FileUploadNotificationProcessorClientOptions options)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification is received from the service. May not be null.

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

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String connectionString,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification is received from the service. May not be null.

FileUploadNotificationProcessorClient

public FileUploadNotificationProcessorClient(String connectionString,
                                             IotHubServiceClientProtocol protocol,
                                             Function<FileUploadNotification,AcknowledgementType> fileUploadNotificationProcessor,
                                             FileUploadNotificationProcessorClientOptions options)

Construct a FileUploadNotificationProcessorClient 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.

fileUploadNotificationProcessor - The callback to be executed each time a file upload notification 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 file upload notifications. When you want to stop processing file upload notifications, 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 file upload notifications. When you want to stop processing file upload notifications, 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 file upload notifications 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.

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 file upload notifications 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 FileUploadNotificationProcessorClientOptions 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.