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 java.lang.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
static class	IotHubTransport.MessageRetryRunnable Task for adding a packet back to the waiting queue.

Constructor Summary

Constructors

Constructor and Description
IotHubTransport(ClientConfiguration defaultConfig, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, boolean isMultiplexing) Constructor for an IotHubTransport object with default values
IotHubTransport(java.lang.String hostName, IotHubClientProtocol protocol, javax.net.ssl.SSLContext sslContext, ProxySettings proxySettings, IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback, int keepAliveInterval, int sendInterval, boolean useIdentifiableThreadNames, java.lang.String threadNamePrefix, java.lang.String threadNameSuffix)

Method Summary

Modifier and Type	Method and Description
void	addMessage(Message message, MessageSentCallback callback, java.lang.Object callbackContext, java.lang.String deviceId) Adds a message to the transport queue.
void	close(IotHubConnectionStatusChangeReason reason, java.lang.Throwable cause) Closes all resources used to communicate with an IoT Hub.
IotHubClientProtocol	getProtocol()
java.util.concurrent.Semaphore	getReceiveThreadSemaphore()
java.util.concurrent.Semaphore	getReconnectThreadSemaphore()
java.util.concurrent.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.
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.
boolean	needsReconnect()
void	onConnectionEstablished(java.lang.String connectionId) Callback to be fired when the connection has been successfully established
void	onConnectionLost(TransportException e, java.lang.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, java.lang.String deviceId, TransportException e) Callback to be fired when a message that the transport client sent has been acknowledged by Iot Hub
void	onMultiplexedDeviceSessionEstablished(java.lang.String connectionId, java.lang.String deviceId) Callback to be fired when the multiplexed connection establishes a new device session.
void	onMultiplexedDeviceSessionLost(TransportException e, java.lang.String connectionId, java.lang.String deviceId, boolean shouldReconnect) Callback to be fired when the multiplexed connection loses a device session.
void	onMultiplexedDeviceSessionRegistrationFailed(java.lang.String connectionId, java.lang.String deviceId, java.lang.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.
void	reconnect()
void	registerMultiplexedDeviceClient(java.util.List<ClientConfiguration> configs, long timeoutMilliseconds)
void	sendMessages() Sends all messages on the transport queue.
void	setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, java.lang.Object callbackContext, java.lang.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, java.lang.Object callbackContext)
void	setMultiplexingRetryPolicy(RetryPolicy retryPolicy)
void	unregisterMultiplexedDeviceClient(java.util.List<ClientConfiguration> 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(ClientConfiguration defaultConfig,
                       IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback,
                       boolean isMultiplexing)
                throws java.lang.IllegalArgumentException

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:

java.lang.IllegalArgumentException - if defaultConfig is null

IotHubTransport

public IotHubTransport(java.lang.String hostName,
                       IotHubClientProtocol protocol,
                       javax.net.ssl.SSLContext sslContext,
                       ProxySettings proxySettings,
                       IotHubConnectionStatusChangeCallback deviceIOConnectionStatusChangeCallback,
                       int keepAliveInterval,
                       int sendInterval,
                       boolean useIdentifiableThreadNames,
                       java.lang.String threadNamePrefix,
                       java.lang.String threadNameSuffix)
                throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

Method Detail

getSendThreadSemaphore

public java.util.concurrent.Semaphore getSendThreadSemaphore()

getReceiveThreadSemaphore

public java.util.concurrent.Semaphore getReceiveThreadSemaphore()

getReconnectThreadSemaphore

public java.util.concurrent.Semaphore getReconnectThreadSemaphore()

hasMessagesToSend

public boolean hasMessagesToSend()

hasReceivedMessagesToHandle

public boolean hasReceivedMessagesToHandle()

hasCallbacksToExecute

public boolean hasCallbacksToExecute()

needsReconnect

public boolean needsReconnect()

isClosed

public boolean isClosed()

onMessageSent

public void onMessageSent(Message message,
                          java.lang.String deviceId,
                          TransportException 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,
                              TransportException 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(TransportException e,
                             java.lang.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(java.lang.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(java.lang.String connectionId,
                                                  java.lang.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

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,
                                           java.lang.String connectionId,
                                           java.lang.String deviceId,
                                           boolean shouldReconnect)

Description copied from interface: IotHubListener

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

Specified by:

onMultiplexedDeviceSessionLost in interface IotHubListener

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(java.lang.String connectionId,
                                                         java.lang.String deviceId,
                                                         java.lang.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(boolean withRetry)
          throws TransportException,
                 IotHubClientException

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.

IotHubClientException

close

public void close(IotHubConnectionStatusChangeReason reason,
                  java.lang.Throwable cause)

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

reconnect

public void reconnect()
               throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

addMessage

public void addMessage(Message message,
                       MessageSentCallback callback,
                       java.lang.Object callbackContext,
                       java.lang.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 TransportException

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.

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.

setConnectionStatusChangeCallback

public void setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback,
                                              java.lang.Object callbackContext,
                                              java.lang.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.

deviceId - the device that the connection status events being subscribed to are for.

setMultiplexingConnectionStateCallback

public void setMultiplexingConnectionStateCallback(IotHubConnectionStatusChangeCallback callback,
                                                   java.lang.Object callbackContext)

registerMultiplexedDeviceClient

public void registerMultiplexedDeviceClient(java.util.List<ClientConfiguration> configs,
                                            long timeoutMilliseconds)
                                     throws java.lang.InterruptedException,
                                            IotHubClientException,
                                            MultiplexingClientRegistrationException

Throws:

java.lang.InterruptedException

IotHubClientException

MultiplexingClientRegistrationException

unregisterMultiplexedDeviceClient

public void unregisterMultiplexedDeviceClient(java.util.List<ClientConfiguration> configs,
                                              long timeoutMilliseconds)
                                       throws java.lang.InterruptedException,
                                              IotHubClientException

Throws:

java.lang.InterruptedException

IotHubClientException

setMaxNumberOfMessagesSentPerSendThread

public void setMaxNumberOfMessagesSentPerSendThread(int maxNumberOfMessagesSentPerSendThread)