com.microsoft.azure.sdk.iot.device

Class InternalClient

java.lang.Object

com.microsoft.azure.sdk.iot.device.InternalClient

Direct Known Subclasses:

DeviceClient, ModuleClient

public class InternalClient
extends java.lang.Object

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	DEFAULT_TIMEOUT_MILLISECONDS

Method Summary

Modifier and Type	Method and Description
void	close() Close the client.
ClientConfiguration	getConfig() Getter for the device client config.
ProductInfo	getProductInfo()
Twin	getTwin() Get the twin for this client.
Twin	getTwin(int timeoutMilliseconds) Get the twin for this client.
void	getTwinAsync(GetTwinCallback twinCallback, java.lang.Object callbackContext) Get the twin for this client asynchronously.
void	getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, java.lang.Object callbackContext) Get the twin for this client asynchronously.
void	open(boolean withRetry) Starts asynchronously sending and receiving messages from an IoT hub.
void	sendEvent(Message message) Synchronously sends a message to IoT hub.
void	sendEvent(Message message, int timeoutMilliseconds) Synchronously sends a message to IoT hub.
void	sendEventAsync(Message message, MessageSentCallback callback, java.lang.Object callbackContext) Asynchronously sends a message to IoT hub.
void	sendEvents(java.util.List<Message> messages) Synchronously sends a batch of messages to IoT hub This operation is only supported over HTTPS.
void	sendEvents(java.util.List<Message> messages, int timeoutMilliseconds) Synchronously sends a batch of messages to IoT hub This operation is only supported over HTTPS.
void	sendEventsAsync(java.util.List<Message> messages, MessagesSentCallback callback, java.lang.Object callbackContext) Asynchronously sends a batch of messages to the IoT hub This operation is only supported over HTTPS.
void	setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, java.lang.Object callbackContext) Sets the callback to be executed when the connection status of the device changes.
void	setOperationTimeout(long timeout) Set the length of time, in milliseconds, that any given operation will expire in.
void	setRetryPolicy(RetryPolicy retryPolicy) Sets the given retry policy on the underlying transport See more details about the default retry policy and about using custom retry policies here
void	subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, java.lang.Object desiredPropertiesCallbackContext) Start receiving desired property updates for this client.
void	subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, java.lang.Object desiredPropertiesCallbackContext, int timeoutMilliseconds) Start receiving desired property updates for this client.
void	subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback, java.lang.Object desiredPropertiesCallbackContext, SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback, java.lang.Object desiredPropertiesSubscriptionCallbackContext) Start receiving desired property updates for this client asynchronously.
void	subscribeToMethods(MethodCallback methodCallback, java.lang.Object methodCallbackContext) Subscribes to direct methods.
void	subscribeToMethods(MethodCallback methodCallback, java.lang.Object methodCallbackContext, int timeoutMilliseconds) Subscribes to direct methods.
void	subscribeToMethodsAsync(MethodCallback methodCallback, java.lang.Object methodCallbackContext, SubscriptionAcknowledgedCallback methodStatusCallback, java.lang.Object methodStatusCallbackContext) Subscribes to direct methods.
ReportedPropertiesUpdateResponse	updateReportedProperties(TwinCollection reportedProperties) Patch this client's twin with the provided reported properties.
ReportedPropertiesUpdateResponse	updateReportedProperties(TwinCollection reportedProperties, int timeoutMilliseconds) Patch this client's twin with the provided reported properties.
void	updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, java.lang.Object callbackContext) Patch this client's twin with the provided reported properties asynchronously.
void	updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback, java.lang.Object callbackContext) Patch this client's twin with the provided reported properties asynchronously.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIMEOUT_MILLISECONDS

protected static final int DEFAULT_TIMEOUT_MILLISECONDS

See Also:

Constant Field Values

Method Detail

open

public void open(boolean withRetry)
          throws IotHubClientException

Starts asynchronously sending and receiving messages from an IoT hub. If the client is already open, the function shall do nothing.

Parameters:

withRetry - if true, this open call will apply the retry policy to allow for the open call to be retried if it fails. Both the operation timeout set in setOperationTimeout(long) and the retry policy set in {setRetryPolicy(RetryPolicy)} will be respected while retrying to open the connection.

Throws:

IotHubClientException - if a connection to an IoT hub cannot be established or if the connection can be established but the service rejects it for any reason.

close

public void close()

Close the client.

sendEvent

public void sendEvent(Message message)
               throws java.lang.InterruptedException,
                      java.lang.IllegalStateException,
                      IotHubClientException

Synchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

sendEvent

public void sendEvent(Message message,
                      int timeoutMilliseconds)
               throws java.lang.InterruptedException,
                      java.lang.IllegalStateException,
                      IotHubClientException

Synchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.

timeoutMilliseconds - The maximum number of milliseconds to wait for the service to acknowledge this message. If 0, then it will wait indefinitely.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

sendEvents

public void sendEvents(java.util.List<Message> messages)
                throws java.lang.InterruptedException,
                       java.lang.IllegalStateException,
                       IotHubClientException,
                       java.lang.UnsupportedOperationException

Synchronously sends a batch of messages to IoT hub This operation is only supported over HTTPS. Maximum payload size for HTTPS is 255KB

Parameters:

messages - the messages to be sent.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

java.lang.UnsupportedOperationException - if the client is not using HTTPS.

sendEvents

public void sendEvents(java.util.List<Message> messages,
                       int timeoutMilliseconds)
                throws java.lang.InterruptedException,
                       java.lang.IllegalStateException,
                       IotHubClientException,
                       java.lang.UnsupportedOperationException

Synchronously sends a batch of messages to IoT hub This operation is only supported over HTTPS. Maximum payload size for HTTPS is 255KB

Parameters:

messages - the messages to be sent.

timeoutMilliseconds - The maximum number of milliseconds to wait for the service to acknowledge this batch message. If 0, then it will wait indefinitely.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the telemetry to be acknowledged by the service.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

java.lang.UnsupportedOperationException - if the client is not using HTTPS.

subscribeToDesiredProperties

public void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback,
                                         java.lang.Object desiredPropertiesCallbackContext)
                                  throws java.lang.InterruptedException,
                                         java.lang.IllegalStateException,
                                         IotHubClientException

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.

desiredPropertiesCallbackContext - The context that will be included in the callback of desiredPropertiesCallback. May be null.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToDesiredProperties

public void subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback,
                                         java.lang.Object desiredPropertiesCallbackContext,
                                         int timeoutMilliseconds)
                                  throws java.lang.InterruptedException,
                                         java.lang.IllegalStateException,
                                         IotHubClientException

Start receiving desired property updates for this client. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.

desiredPropertiesCallbackContext - The context that will be included in the callback of desiredPropertiesCallback. May be null.

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to acknowledge the subscription request. If 0, then it will wait indefinitely.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

updateReportedProperties

public ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties)
                                                          throws java.lang.InterruptedException,
                                                                 java.lang.IllegalStateException,
                                                                 IotHubClientException

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.

Returns:

The new reported properties version.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the reported property update request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

updateReportedProperties

public ReportedPropertiesUpdateResponse updateReportedProperties(TwinCollection reportedProperties,
                                                                 int timeoutMilliseconds)
                                                          throws java.lang.InterruptedException,
                                                                 java.lang.IllegalStateException,
                                                                 IotHubClientException

Patch this client's twin with the provided reported properties. This client must have subscribed to desired properties before this method can be called. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to acknowledge the reported properties update request. If 0, then it will wait indefinitely.

Returns:

The new reported properties version.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the reported property update request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

getTwin

public Twin getTwin()
             throws java.lang.InterruptedException,
                    java.lang.IllegalStateException,
                    IotHubClientException

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.

Returns:

The twin for this client

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the getTwin request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

getTwin

public Twin getTwin(int timeoutMilliseconds)
             throws java.lang.InterruptedException,
                    java.lang.IllegalStateException,
                    IotHubClientException

Get the twin for this client. This client must have subscribed to desired properties before this method can be called.

Parameters:

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to return the twin. If 0, then it will wait indefinitely.

Returns:

The twin for this client

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the getTwin request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToMethods

public void subscribeToMethods(MethodCallback methodCallback,
                               java.lang.Object methodCallbackContext)
                        throws java.lang.IllegalStateException,
                               java.lang.InterruptedException,
                               IotHubClientException

Subscribes to direct methods.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

methodCallback - Callback on which direct methods shall be invoked. Cannot be null.

methodCallbackContext - Context for device method callback. Can be null.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

subscribeToMethods

public void subscribeToMethods(MethodCallback methodCallback,
                               java.lang.Object methodCallbackContext,
                               int timeoutMilliseconds)
                        throws java.lang.IllegalStateException,
                               java.lang.InterruptedException,
                               IotHubClientException

Subscribes to direct methods.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

methodCallback - Callback on which direct methods shall be invoked. Cannot be null.

methodCallbackContext - Context for device method callback. Can be null.

timeoutMilliseconds - The maximum number of milliseconds this call will wait for the service to return the twin. If 0, then it will wait indefinitely.

Throws:

java.lang.InterruptedException - if the operation is interrupted while waiting on the subscription request to be acknowledged by the service.

java.lang.IllegalStateException - if this client is not open.

IotHubClientException - if the request is rejected by the service for any reason of if the synchronous operation times out.

sendEventAsync

public void sendEventAsync(Message message,
                           MessageSentCallback callback,
                           java.lang.Object callbackContext)
                    throws java.lang.IllegalStateException

Asynchronously sends a message to IoT hub.

Parameters:

message - the message to be sent.

callback - the callback to be invoked when a response is received. Can be null.

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

Throws:

java.lang.IllegalArgumentException - if the message provided is null.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

sendEventsAsync

public void sendEventsAsync(java.util.List<Message> messages,
                            MessagesSentCallback callback,
                            java.lang.Object callbackContext)
                     throws java.lang.IllegalStateException,
                            java.lang.UnsupportedOperationException

Asynchronously sends a batch of messages to the IoT hub This operation is only supported over HTTPS. This API call is an all-or-nothing single HTTPS message and the callback will be triggered once this batch message has been sent. Maximum payload size for HTTPS is 255KB

Parameters:

messages - the list of message to be sent.

callback - the callback to be invoked when a response is received. Can be null.

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

Throws:

java.lang.IllegalArgumentException - if the message provided is null.

java.lang.IllegalStateException - if the client has not been opened yet or is already closed.

java.lang.UnsupportedOperationException - if the client is not using HTTPS.

subscribeToDesiredPropertiesAsync

public void subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback,
                                              java.lang.Object desiredPropertiesCallbackContext,
                                              SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback,
                                              java.lang.Object desiredPropertiesSubscriptionCallbackContext)
                                       throws java.lang.IllegalStateException

Start receiving desired property updates for this client asynchronously. After subscribing to desired properties, this client can freely send reported property updates and make getTwin calls.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

subscriptionAcknowledgedCallback - The callback to execute once the service has acknowledged the subscription request.

desiredPropertiesSubscriptionCallbackContext - The context that will be included in the callback of desiredPropertiesSubscriptionCallback. May be null.

desiredPropertiesCallback - The callback to execute each time a desired property update message is received from the service. This will contain one or many properties updated at once.

desiredPropertiesCallbackContext - The context that will be included in each callback of desiredPropertiesCallback. May be null.

Throws:

java.lang.IllegalStateException - if this client is not open.

updateReportedPropertiesAsync

public void updateReportedPropertiesAsync(TwinCollection reportedProperties,
                                          ReportedPropertiesCallback reportedPropertiesCallback,
                                          java.lang.Object callbackContext)
                                   throws java.lang.IllegalStateException

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.

reportedPropertiesCallback - The callback to be executed once the reported properties update request has been acknowledged by the service.

callbackContext - The context that will be included in the callback of reportedPropertiesCallback. May be null.

Throws:

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

updateReportedPropertiesAsync

public void updateReportedPropertiesAsync(TwinCollection reportedProperties,
                                          ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback,
                                          java.lang.Object callbackContext)
                                   throws java.lang.IllegalStateException

Patch this client's twin with the provided reported properties asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than updateReportedPropertiesAsync(TwinCollection, ReportedPropertiesCallback, Object) and is only intended for users who need insight on the state of this process every step of the way.

Parameters:

reportedProperties - The reported property key/value pairs to add/update in the twin. To delete a particular reported property, set the value to null.

reportedPropertiesUpdateCorrelatingMessageCallback - The callback to be executed once the state of the reported properties update request message has changed. This provides context on when the message is queued, sent, acknowledged, etc.

callbackContext - The context that will be included in each callback of updateReportedPropertiesCallback. May be null.

Throws:

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

getTwinAsync

public void getTwinAsync(GetTwinCallback twinCallback,
                         java.lang.Object callbackContext)
                  throws java.lang.IllegalStateException

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.

Parameters:

twinCallback - The callback to be executed once the twin is received from the service.

callbackContext - The context that will be included in the callback of twinCallback. May be null.

Throws:

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

getTwinAsync

public void getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback,
                         java.lang.Object callbackContext)
                  throws java.lang.IllegalStateException

Get the twin for this client asynchronously. This client must have subscribed to desired properties before this method can be called.

This overload utilizes a more verbose callback than getTwinAsync(GetTwinCallback, Object) and is only intended for users who need insight on the state of this process every step of the way.

Parameters:

twinCallback - The callback to be executed once the state of the getTwin request message has changed. This provides context on when the message is queued, sent, acknowledged, etc.

callbackContext - The context that will be included in each callback of twinCallback. May be null.

Throws:

java.lang.IllegalStateException - if this client is not open or if this client has not subscribed to desired properties yet.

subscribeToMethodsAsync

public void subscribeToMethodsAsync(MethodCallback methodCallback,
                                    java.lang.Object methodCallbackContext,
                                    SubscriptionAcknowledgedCallback methodStatusCallback,
                                    java.lang.Object methodStatusCallbackContext)
                             throws java.lang.IllegalStateException

Subscribes to direct methods.

This call can only be made after the client has been successfully opened.

This subscription is preserved between reconnect attempts. However, it is not preserved after a client has been closed because the user called close() or because this client lost its connection and its retry policy was exhausted.

Parameters:

methodCallback - Callback on which direct methods shall be invoked. Cannot be null.

methodCallbackContext - Context for device method callback. Can be null.

methodStatusCallback - Callback for providing IotHub status for direct methods. Cannot be null.

methodStatusCallbackContext - Context for device method status callback. Can be null.

Throws:

java.lang.IllegalStateException - if called when client is not opened.

java.lang.IllegalArgumentException - if either callback are null.

setConnectionStatusChangeCallback

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

Sets the callback to be executed when the connection status of the device changes. The callback will be fired with a status and a reason why the device's status changed. When the callback is fired, the provided context will be provided alongside the status and reason. This connection status callback is not triggered by any upstream connection change events. For example, if if the connection status callback is set for a module on an IoT Edge device and that IoT Edge device loses connection to the cloud, this connection status callback won't onStatusChanged since the connection between the module and the IoT Edge device hasn't changed.

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()/close() operations should be done on a separate thread

Parameters:

callback - The callback to be fired when the connection status of the device 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.

setRetryPolicy

public void setRetryPolicy(RetryPolicy retryPolicy)

Sets the given retry policy on the underlying transport See more details about the default retry policy and about using custom retry policies here

Parameters:

retryPolicy - the new interval in milliseconds

setOperationTimeout

public void setOperationTimeout(long timeout)
                         throws java.lang.IllegalArgumentException

Set the length of time, in milliseconds, that any given operation will expire in. These operations include reconnecting upon a connection drop and sending a message.

Parameters:

timeout - the length in time, in milliseconds, until a given operation shall expire

Throws:

java.lang.IllegalArgumentException - if the provided timeout is 0 or negative

getProductInfo

public ProductInfo getProductInfo()

getConfig

public ClientConfiguration getConfig()

Getter for the device client config.

Returns:

the value of the config.