IotHubTransport Class

  • Reference
Package:
com.microsoft.azure.sdk.iot.device.transport
  • java.lang.Object
    • IotHubListener
      • com.microsoft.azure.sdk.iot.device.transport.IotHubTransport

public class IotHubTransport implements IotHubListener

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

Constructor Summary

Constructor Description
IotHubTransport(ClientConfiguration defaultConfig, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, boolean isMultiplexing)

Constructor for an IotHubTransport object with default values
IotHubTransport(String hostName, IotHubClientProtocol protocol, SSLContext sslContext, ProxySettings proxySettings, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, int keepAliveInterval)

Method Summary

Modifier and Type Method and Description
void addMessage(Message message, MessageSentCallback 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. Onceclose()  

</code> is called, the transport is no longer usable. If the transport is already closed, the function shall do nothing.</p>

IotHubClientProtocol getProtocol()
Semaphore getReceiveThreadSemaphore()
Semaphore getReconnectThreadSemaphore()
Semaphore getSendThreadSemaphore()
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.

If no message callback is set, the function will do nothing.
boolean hasCallbacksToExecute()
boolean hasMessagesToSend()
boolean hasReceivedMessagesToHandle()
void invokeCallbacks()

Invokes the callbacks for all completed requests.

boolean isClosed()
boolean isEmpty()

Returnstrue  

</code> if the transport has no more messages to handle, and<code>false 

</code> otherwise.</p>

boolean needsReconnect()
void onConnectionEstablished(String connectionId)

Callback to be fired when the connection has been successfully established

void onConnectionLost(TransportException e, String connectionId)

Callback to be fired when connection has been lost

void onMessageReceived(IotHubTransportMessage message, TransportException e)

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

void onMessageSent(Message message, String deviceId, TransportException 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(TransportException e, String connectionId, String deviceId, boolean shouldReconnect)

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(boolean withRetry)

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
void reconnect()
void registerMultiplexedDeviceClient(List<ClientConfiguration> configs, long timeoutMilliseconds)
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.

void setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext, String deviceId)

Registers a callback to be executed whenever the connection status to the IoT Hub has changed.
void setMaxNumberOfMessagesSentPerSendThread(int maxNumberOfMessagesSentPerSendThread)
void setMultiplexingConnectionStateCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)
void setMultiplexingRetryPolicy(RetryPolicy retryPolicy)
void unregisterMultiplexedDeviceClient(List<ClientConfiguration> configs, long timeoutMilliseconds)

Constructor Details

IotHubTransport

public IotHubTransport(ClientConfiguration defaultConfig, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, boolean isMultiplexing)

Constructor for an IotHubTransport object with default values

Parameters:

defaultConfig - the config used for opening connections, retrieving retry policy, and checking protocol
deviceIOConnectionStatusChangeCallback - the connection status callback used to notify the DeviceIO layer when connection events happen.
isMultiplexing - true if this connection will multiplex. False otherwise.

Throws:

IllegalArgumentException - if defaultConfig is null

IotHubTransport

public IotHubTransport(String hostName, IotHubClientProtocol protocol, SSLContext sslContext, ProxySettings proxySettings, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, int keepAliveInterval)

Parameters:

hostName
protocol
sslContext
proxySettings
deviceIOConnectionStatusChangeCallback
keepAliveInterval

Method Details

addMessage

public void addMessage(Message message, MessageSentCallback 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.

close

public void close(IotHubConnectionStatusChangeReason reason, Throwable cause)

Closes all resources used to communicate with an IoT Hub. Onceclose()  

</code> is called, the transport is no longer usable. If the transport is already closed, the function shall do nothing.</p>

Parameters:

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

getProtocol

public IotHubClientProtocol getProtocol()

getReceiveThreadSemaphore

public Semaphore getReceiveThreadSemaphore()

getReconnectThreadSemaphore

public Semaphore getReconnectThreadSemaphore()

getSendThreadSemaphore

public Semaphore getSendThreadSemaphore()

handleMessage

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

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

Throws:

TransportException - if the server could not be reached.

hasCallbacksToExecute

public boolean hasCallbacksToExecute()

hasMessagesToSend

public boolean hasMessagesToSend()

hasReceivedMessagesToHandle

public boolean hasReceivedMessagesToHandle()

invokeCallbacks

public void invokeCallbacks()

Invokes the callbacks for all completed requests.

isClosed

public boolean isClosed()

isEmpty

public boolean isEmpty()

Returnstrue  

</code> if the transport has no more messages to handle, and<code>false 

</code> otherwise.</p>

Returns:

true  

</code> if the transport has no more messages to handle, and<code>false 

</code> otherwise. </p>

needsReconnect

public boolean needsReconnect()

onConnectionEstablished

public void onConnectionEstablished(String connectionId)

Callback to be fired when the connection has been successfully established

Overrides:

IotHubTransport.onConnectionEstablished(String connectionId)

Parameters:

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

onConnectionLost

public void onConnectionLost(TransportException e, String connectionId)

Callback to be fired when connection has been lost

Overrides:

IotHubTransport.onConnectionLost(TransportException e, String connectionId)

Parameters:

e - the cause of the connection loss
connectionId - the id of the connection this update is relevant to

onMessageReceived

public void onMessageReceived(IotHubTransportMessage message, TransportException e)

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

Overrides:

IotHubTransport.onMessageReceived(IotHubTransportMessage message, TransportException e)

Parameters:

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

onMessageSent

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

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

Overrides:

IotHubTransport.onMessageSent(Message message, String deviceId, TransportException e)

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

onMultiplexedDeviceSessionEstablished

public void onMultiplexedDeviceSessionEstablished(String connectionId, String deviceId)

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

Overrides:

IotHubTransport.onMultiplexedDeviceSessionEstablished(String connectionId, String deviceId)

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

onMultiplexedDeviceSessionLost

public void onMultiplexedDeviceSessionLost(TransportException e, String connectionId, String deviceId, boolean shouldReconnect)

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

Overrides:

IotHubTransport.onMultiplexedDeviceSessionLost(TransportException e, String connectionId, String deviceId, boolean shouldReconnect)

Parameters:

e - The exception that caused the connection to be lost.
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
shouldReconnect - false if the disconnect was desired by the users, and true if it is the consequence of an issue where the SDK should retry.

onMultiplexedDeviceSessionRegistrationFailed

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

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

Overrides:

IotHubTransport.onMultiplexedDeviceSessionRegistrationFailed(String connectionId, String deviceId, Exception e)

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.

open

public void open(boolean withRetry)

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

Parameters:

withRetry - if true, this open call will apply the current retry policy to allow for the open call to be retried if it fails.

Throws:

TransportException - if a communication channel cannot be established.

reconnect

public void reconnect()

registerMultiplexedDeviceClient

public void registerMultiplexedDeviceClient(List configs, long timeoutMilliseconds)

Parameters:

configs
timeoutMilliseconds

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.

setConnectionStatusChangeCallback

public void setConnectionStatusChangeCallback(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 benull  

</code> . </p>
deviceId - the device that the connection status events being subscribed to are for.

setMaxNumberOfMessagesSentPerSendThread

public void setMaxNumberOfMessagesSentPerSendThread(int maxNumberOfMessagesSentPerSendThread)

Parameters:

maxNumberOfMessagesSentPerSendThread

setMultiplexingConnectionStateCallback

public void setMultiplexingConnectionStateCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext)

Parameters:

callback
callbackContext

setMultiplexingRetryPolicy

public void setMultiplexingRetryPolicy(RetryPolicy retryPolicy)

Parameters:

retryPolicy

unregisterMultiplexedDeviceClient

public void unregisterMultiplexedDeviceClient(List configs, long timeoutMilliseconds)

Parameters:

configs
timeoutMilliseconds

Applies to