MultiplexingClient Class

Modifier and Type	Field and Description
static final long	DEFAULT_RECEIVE_PERIOD_MILLIS
static final long	DEFAULT_SEND_PERIOD_MILLIS
static final int	MAX_MULTIPLEX_DEVICE_COUNT_AMQPS The maximum number of devices that can be multiplexed together on a single multiplexed AMQPS connection
static final int	MAX_MULTIPLEX_DEVICE_COUNT_AMQPS_WS The maximum number of devices that can be multiplexed together on a single multiplexed AMQPS_WS connection

Constructor	Description
MultiplexingClient(String hostName, IotHubClientProtocol protocol)	Instantiate a new MultiplexingClient that will establish a multiplexed connection through a proxy.
MultiplexingClient(String hostName, IotHubClientProtocol protocol, MultiplexingClientOptions options)	Instantiate a new MultiplexingClient that will establish a multiplexed connection through a proxy.

Modifier and Type	Method and Description
void	close() Close this multiplexing client.
int	getRegisteredDeviceCount() Get the number of currently registered devices on this multiplexing client.
boolean	isDeviceRegistered(String deviceId) Returns if a device client for the provided device Id is already registered to this multiplexing client.
void	open() Opens this multiplexing client.
void	registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext) Registers a callback to be executed when the connection status of the multiplexed connection as a whole changes.
void	registerDeviceClient(DeviceClient deviceClient) Register a device client to this multiplexing client.
void	registerDeviceClient(DeviceClient deviceClient, long timeoutMilliseconds) Register a device client to this multiplexing client.
void	registerDeviceClients(Iterable<DeviceClient> deviceClients) Register multiple device clients to this multiplexing client.
void	registerDeviceClients(Iterable<DeviceClient> deviceClients, long timeoutMilliseconds) Register multiple device clients to this multiplexing client.
void	setRetryPolicy(RetryPolicy retryPolicy) Sets the given retry policy for the multiplexing client level connection management.
void	unregisterDeviceClient(DeviceClient deviceClient) Unregister a device client from this multiplexing client.
void	unregisterDeviceClient(DeviceClient deviceClient, long timeoutMilliseconds) Unregister a device client from this multiplexing client.
void	unregisterDeviceClients(Iterable<DeviceClient> deviceClients) Unregister multiple device clients from this multiplexing client.
void	unregisterDeviceClients(Iterable<DeviceClient> deviceClients, long timeoutMilliseconds) Unregister multiple device clients from this multiplexing client.

DEFAULT_RECEIVE_PERIOD_MILLIS

public static final long DEFAULT_RECEIVE_PERIOD_MILLIS

DEFAULT_SEND_PERIOD_MILLIS

public static final long DEFAULT_SEND_PERIOD_MILLIS

MAX_MULTIPLEX_DEVICE_COUNT_AMQPS

public static final int MAX_MULTIPLEX_DEVICE_COUNT_AMQPS

The maximum number of devices that can be multiplexed together on a single multiplexed AMQPS connection

MAX_MULTIPLEX_DEVICE_COUNT_AMQPS_WS

public static final int MAX_MULTIPLEX_DEVICE_COUNT_AMQPS_WS

The maximum number of devices that can be multiplexed together on a single multiplexed AMQPS_WS connection

MultiplexingClient

public MultiplexingClient(String hostName, IotHubClientProtocol protocol)

Instantiate a new MultiplexingClient that will establish a multiplexed connection through a proxy.

Parameters:

hostName

protocol - The transport protocol that this client will build the multiplexed connection on. Must be either AMQPS or AMQPS_WS.

MultiplexingClient

public MultiplexingClient(String hostName, IotHubClientProtocol protocol, MultiplexingClientOptions options)

Instantiate a new MultiplexingClient that will establish a multiplexed connection through a proxy.

Parameters:

hostName

protocol - The transport protocol that this client will build the multiplexed connection on. Must be AMQPS_WS since using AMQPS does not support proxies.

options - The optional parameters to configure this client to use.

close

public void close()

Close this multiplexing client. This will close all active device sessions as well as the AMQP connection.

If this client is already closed, then this method will do nothing.

Once closed, this client can be re-opened. It will preserve all previously registered device clients.

Throws:

MultiplexingClientException - If any IO errors occur when fulfilling this request.

getRegisteredDeviceCount

public int getRegisteredDeviceCount()

Get the number of currently registered devices on this multiplexing client.

Returns:

The number of currently registered devices on this multiplexing client.

isDeviceRegistered

public boolean isDeviceRegistered(String deviceId)

Returns if a device client for the provided device Id is already registered to this multiplexing client.

Parameters:

deviceId - The Id of the device client to look for.

Returns:

True if a device client is already registered with this Id. False otherwise.

open

public void open()

Opens this multiplexing client. This may be done before or after registering any number of device clients.

This call behaves synchronously, so if it returns without throwing, then all registered device clients were successfully opened.

If this client is already open, then this method will do nothing.

Throws:

MultiplexingClientException - If any IO or authentication errors occur while opening the multiplexed connection.

registerConnectionStatusChangeCallback

public void registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

Registers a callback to be executed when the connection status of the multiplexed connection as a whole changes. The callback will be fired with a status and a reason why the multiplexed connection's status changed. When the callback is fired, the provided context will be provided alongside the status and reason.

Note that this callback will not be fired for device specific connection status changes. In order to be notified when a particular device's connection status changes, you will need to register a connection status change callback on that device client instance using DeviceClient#registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback, Object).

Note that the thread used to deliver this callback should not be used to call open()/closeNow() on the client that this callback belongs to. All open()/closeNow() operations should be done on a separate thread

Parameters:

callback - The callback to be fired when the connection status of the multiplexed connection changes. Can be null to unset this listener as long as the provided callbackContext is also null.

callbackContext - a context to be passed to the callback. Can be null.

registerDeviceClient

public void registerDeviceClient(DeviceClient deviceClient)

Register a device client to this multiplexing client. This method may be called before or after opening the multiplexed connection.

Users should use registerDeviceClients(Iterable<DeviceClient> deviceClients) for registering multiple devices as it has some performance improvements over repeatedly calling this method for individual device registrations. This method blocks on each registration, whereas registerDeviceClients(Iterable<DeviceClient> deviceClients) blocks on all of the registrations after starting them all asynchronously.

A device client can be unregistered using unregisterDeviceClient(DeviceClient deviceClient), unregisterDeviceClient(DeviceClient deviceClient, long timeoutMilliseconds), unregisterDeviceClients(Iterable<DeviceClient> deviceClients), or unregisterDeviceClients(Iterable<DeviceClient> deviceClients, long timeoutMilliseconds). A device client will not be unregistered automatically if it encounters a non-retryable exception, so users are responsible for unregistering a device client when they no longer want it in this multiplexing client.

Up to MAX_MULTIPLEX_DEVICE_COUNT_AMQPS devices can be registered on a multiplexed AMQPS connection, and up to MAX_MULTIPLEX_DEVICE_COUNT_AMQPS_WS devices can be registered on a multiplexed AMQPS_WS connection.

If the multiplexing client is already open, then this device client will automatically be opened, too. If the multiplexing client is not open yet, then this device client will not be opened until open() is called.

If the multiplexed connection is already open, then this call will add this device client to the multiplexed connection, and then will block until the registration has been completed.

Any proxy settings set to the provided device clients will be overwritten by the proxy settings of this multiplexing client.

The registered device client must use the same transport protocol (AMQPS or AMQPS_WS) that this multiplexing client uses.

Each registered device client may have its own retry policy and its own SAS token expiry time, separate from every other registered device client.

The registered device client must use symmetric key based authentication.

The registered device client must belong to the same IoT Hub as all previously registered device clients.

If the provided device client is already registered to this multiplexing client, then then this method will do nothing.

Any subscriptions (twin, methods, cloud to device messages) set on this device client from when it was previously registered to any multiplexing client will need to be set again as subscriptions and their callbacks are not preserved.

Parameters:

deviceClient - The device client to associate with this multiplexing client.

Throws:

java.lang.InterruptedException - If the thread gets interrupted while waiting for the registration to succeed. This will never be thrown if the multiplexing client is not open yet.

MultiplexingClientException - If the thread gets interrupted while waiting for the registration to succeed. This will never be thrown if the multiplexing client is not open yet.

registerDeviceClient

public void registerDeviceClient(DeviceClient deviceClient, long timeoutMilliseconds)