com.microsoft.azure.sdk.iot.device.transport

Class IotHubTransport

java.lang.Object

com.microsoft.azure.sdk.iot.device.transport.IotHubTransport

All Implemented Interfaces:

IotHubListener

public class IotHubTransport
extends Object
implements IotHubListener

Manages queueing of message sending, receiving and callbacks. Manages notifying users of connection status change updates

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	IotHubTransport.MessageRetryRunnable Task for adding a packet back to the waiting queue.

Constructor Summary

Constructors

Constructor and Description
IotHubTransport(DeviceClientConfig defaultConfig, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback) Constructor for an IotHubTransport object with default values
IotHubTransport(String hostName, IotHubClientProtocol protocol, SSLContext sslContext, ProxySettings proxySettings, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback)

Method Summary

Modifier and Type	Method and Description
void	addMessage(Message message, IotHubEventCallback callback, Object callbackContext, String deviceId) Adds a message to the transport queue.
void	close(IotHubConnectionStatusChangeReason reason, Throwable cause) Closes all resources used to communicate with an IoT Hub.
IotHubClientProtocol	getProtocol()
Object	getReceiveThreadLock()
Object	getSendThreadLock()
void	handleMessage() Invokes the message callback if a message is found and responds to the IoT Hub on how the processed message should be handled by the IoT Hub.
boolean	hasCallbacksToExecute()
boolean	hasMessagesToSend()
boolean	hasReceivedMessagesToHandle()
void	invokeCallbacks() Invokes the callbacks for all completed requests.
boolean	isClosed()
boolean	isEmpty() Returns true if the transport has no more messages to handle, and false otherwise.
void	onConnectionEstablished(String connectionId) Callback to be fired when the connection has been successfully established
void	onConnectionLost(Throwable e, String connectionId) Callback to be fired when connection has been lost
void	onMessageReceived(IotHubTransportMessage message, Throwable e) Callback to be fired when a transport message has been received.
void	onMessageSent(Message message, String deviceId, Throwable e) Callback to be fired when a message that the transport client sent has been acknowledged by Iot Hub
void	onMultiplexedDeviceSessionEstablished(String connectionId, String deviceId) Callback to be fired when the multiplexed connection establishes a new device session.
void	onMultiplexedDeviceSessionLost(Throwable e, String connectionId, String deviceId) Callback to be fired when the multiplexed connection loses a device session.
void	onMultiplexedDeviceSessionRegistrationFailed(String connectionId, String deviceId, Exception e) Callback to be fired when the multiplexed connection fails to register a device session.
void	open() Establishes a communication channel with an IoT Hub.
void	registerConnectionStateCallback(IotHubConnectionStateCallback callback, Object callbackContext) Registers a callback to be executed whenever the connection to the IoT Hub is lost or established.
void	registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext, String deviceId) Registers a callback to be executed whenever the connection status to the IoT Hub has changed.
void	registerMultiplexedDeviceClient(List<DeviceClientConfig> configs, long timeoutMilliseconds)
void	registerMultiplexingConnectionStateCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)
void	sendMessages() Sends all messages on the transport queue.
void	setMultiplexingRetryPolicy(RetryPolicy retryPolicy)
void	unregisterMultiplexedDeviceClient(List<DeviceClientConfig> configs, long timeoutMilliseconds)

Methods inherited from class java.lang.Object

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

Constructor Detail

IotHubTransport

public IotHubTransport(DeviceClientConfig defaultConfig,
                       IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback)
                throws IllegalArgumentException

Constructor for an IotHubTransport object with default values

Parameters:

defaultConfig - the config used for opening connections, retrieving retry policy, and checking protocol

Throws:

IllegalArgumentException - if defaultConfig is null

IotHubTransport

public IotHubTransport(String hostName,
                       IotHubClientProtocol protocol,
                       SSLContext sslContext,
                       ProxySettings proxySettings,
                       IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback)
                throws IllegalArgumentException

Throws:

IllegalArgumentException

Method Detail

getSendThreadLock

public Object getSendThreadLock()

getReceiveThreadLock

public Object getReceiveThreadLock()

hasMessagesToSend

public boolean hasMessagesToSend()

hasReceivedMessagesToHandle

public boolean hasReceivedMessagesToHandle()

hasCallbacksToExecute

public boolean hasCallbacksToExecute()

isClosed

public boolean isClosed()

onMessageSent

public void onMessageSent(Message message,
                          String deviceId,
                          Throwable e)

Description copied from interface: IotHubListener

Callback to be fired when a message that the transport client sent has been acknowledged by Iot Hub

Specified by:

onMessageSent in interface IotHubListener

Parameters:

message - The message that was acknowledged

deviceId - The device that the message was sent from

e - Null if the message was successfully acknowledged. Otherwise, this exception communicates if the message should be resent at all

onMessageReceived

public void onMessageReceived(IotHubTransportMessage message,
                              Throwable e)

Description copied from interface: IotHubListener

Callback to be fired when a transport message has been received.

Specified by:

onMessageReceived in interface IotHubListener

Parameters:

message - The message that was received. May be null if e is not null

e - the exception that was encountered while receiving messages. May be null if transportMessage is not null

onConnectionLost

public void onConnectionLost(Throwable e,
                             String connectionId)

Description copied from interface: IotHubListener

Callback to be fired when connection has been lost

Specified by:

onConnectionLost in interface IotHubListener

Parameters:

e - the cause of the connection loss

connectionId - the id of the connection this update is relevant to

onConnectionEstablished

public void onConnectionEstablished(String connectionId)

Description copied from interface: IotHubListener

Callback to be fired when the connection has been successfully established

Specified by:

onConnectionEstablished in interface IotHubListener

Parameters:

connectionId - the id of the connection this update is relevant to

onMultiplexedDeviceSessionEstablished

public void onMultiplexedDeviceSessionEstablished(String connectionId,
                                                  String deviceId)

Description copied from interface: IotHubListener

Callback to be fired when the multiplexed connection establishes a new device session.

Specified by:

onMultiplexedDeviceSessionEstablished in interface IotHubListener

deviceId - the Id of the device that the session belongs to

onMultiplexedDeviceSessionLost

public void onMultiplexedDeviceSessionLost(Throwable e,
                                           String connectionId,
                                           String deviceId)

Description copied from interface: IotHubListener

Callback to be fired when the multiplexed connection loses a device session.

Specified by:

onMultiplexedDeviceSessionLost in interface IotHubListener

deviceId - the Id of the device that the session belongs to

onMultiplexedDeviceSessionRegistrationFailed

public void onMultiplexedDeviceSessionRegistrationFailed(String connectionId,
                                                         String deviceId,
                                                         Exception e)

Description copied from interface: IotHubListener

Callback to be fired when the multiplexed connection fails to register a device session.

Specified by:

onMultiplexedDeviceSessionRegistrationFailed in interface IotHubListener

Parameters:

connectionId - the Id of the connection, used to identify which of possible many reconnection attempts this event belongs to.

deviceId - the Id of the device that the session belongs to

e - the throwable that explains why the registration failed.

setMultiplexingRetryPolicy

public void setMultiplexingRetryPolicy(RetryPolicy retryPolicy)

open

public void open()
          throws TransportException

Establishes a communication channel with an IoT Hub. If a channel is already open, the function shall do nothing. If reconnection is occurring when this is called, this function shall block and wait for the reconnection to finish before trying to open the connection

Throws:

TransportException - if a communication channel cannot be established.

close

public void close(IotHubConnectionStatusChangeReason reason,
                  Throwable cause)
           throws DeviceClientException

Closes all resources used to communicate with an IoT Hub. Once close() is called, the transport is no longer usable. If the transport is already closed, the function shall do nothing.

Parameters:

cause - the cause of why this connection is closing, to be reported over connection status change callback

reason - the reason to close this connection, to be reported over connection status change callback

Throws:

DeviceClientException - if an error occurs in closing the transport.

addMessage

public void addMessage(Message message,
                       IotHubEventCallback callback,
                       Object callbackContext,
                       String deviceId)

Adds a message to the transport queue.

Parameters:

message - the message to be sent.

callback - the callback to be invoked when a response for the message is received.

callbackContext - the context to be passed in when the callback is

deviceId - the Id of the device that is sending this message. invoked.

getProtocol

public IotHubClientProtocol getProtocol()

sendMessages

public void sendMessages()

Sends all messages on the transport queue. If a previous send attempt had failed, the function will attempt to resend the messages in the previous attempt.

invokeCallbacks

public void invokeCallbacks()

Invokes the callbacks for all completed requests.

handleMessage

public void handleMessage()
                   throws DeviceClientException

Invokes the message callback if a message is found and responds to the IoT Hub on how the processed message should be handled by the IoT Hub.

If no message callback is set, the function will do nothing.

Throws:

DeviceClientException - if the server could not be reached.

isEmpty

public boolean isEmpty()

Returns true if the transport has no more messages to handle, and false otherwise.

Returns:

true if the transport has no more messages to handle, and false otherwise.

registerConnectionStateCallback

public void registerConnectionStateCallback(IotHubConnectionStateCallback callback,
                                            Object callbackContext)

Registers a callback to be executed whenever the connection to the IoT Hub is lost or established.

Parameters:

callback - the callback to be called.

callbackContext - a context to be passed to the callback. Can be null if no callback is provided.

registerConnectionStatusChangeCallback

public void registerConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback,
                                                   Object callbackContext,
                                                   String deviceId)

Registers a callback to be executed whenever the connection status to the IoT Hub has changed.

Parameters:

callback - the callback to be called. Can be null if callbackContext is not null

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

registerMultiplexingConnectionStateCallback

public void registerMultiplexingConnectionStateCallback(IotHubConnectionStatusChangeCallback callback,
                                                        Object callbackContext)

registerMultiplexedDeviceClient

public void registerMultiplexedDeviceClient(List<DeviceClientConfig> configs,
                                            long timeoutMilliseconds)
                                     throws InterruptedException,
                                            MultiplexingClientException

Throws:

InterruptedException

MultiplexingClientException

unregisterMultiplexedDeviceClient

public void unregisterMultiplexedDeviceClient(List<DeviceClientConfig> configs,
                                              long timeoutMilliseconds)
                                       throws InterruptedException,
                                              MultiplexingClientException

Throws:

InterruptedException

MultiplexingClientException