com.microsoft.azure.sdk.iot.device

Class ModuleClient

java.lang.Object

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

com.microsoft.azure.sdk.iot.device.ModuleClient

public class ModuleClient
extends InternalClient

Public API for communicating from Edge Modules. A ModuleClient can be used to send messages from an Edge module to an EdgeHub or an IotHub. It can also send twin updates and listen for method calls from an EdgeHub or IotHub as well

Field Summary

Fields inherited from class com.microsoft.azure.sdk.iot.device.InternalClient

DEFAULT_TIMEOUT_MILLISECONDS

Constructor Summary

Constructors

Constructor and Description
ModuleClient(java.lang.String connectionString, IotHubClientProtocol protocol) Constructor for a ModuleClient instance.
ModuleClient(java.lang.String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) Constructor for a ModuleClient instance.
ModuleClient(java.lang.String hostName, java.lang.String deviceId, java.lang.String moduleId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol) Constructor that allows for the client's SAS token generation to be controlled by the user.
ModuleClient(java.lang.String hostName, java.lang.String deviceId, java.lang.String moduleId, SasTokenProvider sasTokenProvider, IotHubClientProtocol protocol, ClientOptions clientOptions) Constructor that allows for the client's SAS token generation to be controlled by the user.

Method Summary

Modifier and Type	Method and Description
static ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel) Create a module client instance from your environment variables
static ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel, IotHubClientProtocol protocol) Create a module client instance from your environment variables
static ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel, IotHubClientProtocol protocol, ClientOptions clientOptions) Create a module client instance from your environment variables
DirectMethodResponse	invokeMethod(java.lang.String deviceId, DirectMethodRequest directMethodRequest) Invoke a method on a device
DirectMethodResponse	invokeMethod(java.lang.String deviceId, java.lang.String moduleId, DirectMethodRequest directMethodRequest) Invoke a method on a module
void	sendEvent(Message message) Synchronously sends a message to IoT hub.
void	sendEvent(Message message, java.lang.String outputName) Synchronously sends a message to to a particular outputName.
void	sendEvent(Message message, java.lang.String outputName, int timeoutMilliseconds) Synchronously sends a message to to a particular outputName.
void	sendEventAsync(Message message, MessageSentCallback callback, java.lang.Object callbackContext) Asynchronously sends a message to IoT hub.
void	sendEventAsync(Message message, MessageSentCallback callback, java.lang.Object callbackContext, java.lang.String outputName) Sends a message to a particular outputName asynchronously
ModuleClient	setMessageCallback(MessageCallback callback, java.lang.Object context) Sets the message callback.
ModuleClient	setMessageCallback(java.lang.String inputName, MessageCallback callback, java.lang.Object context) Sets the message callback to be fired when a telemetry message arrives on the specified input channel.

Methods inherited from class com.microsoft.azure.sdk.iot.device.InternalClient

close, getConfig, getProductInfo, getTwin, getTwin, getTwinAsync, getTwinAsync, open, sendEvent, sendEvents, sendEvents, sendEventsAsync, setConnectionStatusChangeCallback, setOperationTimeout, setRetryPolicy, subscribeToDesiredProperties, subscribeToDesiredProperties, subscribeToDesiredPropertiesAsync, subscribeToMethods, subscribeToMethods, subscribeToMethodsAsync, updateReportedProperties, updateReportedProperties, updateReportedPropertiesAsync, updateReportedPropertiesAsync

Methods inherited from class java.lang.Object

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

Constructor Detail

ModuleClient

public ModuleClient(java.lang.String connectionString,
                    IotHubClientProtocol protocol)
             throws java.lang.IllegalArgumentException,
                    java.lang.UnsupportedOperationException

Constructor for a ModuleClient instance.

Parameters:

connectionString - The connection string for the edge module to connect to. Must be in format HostName=xxxx;deviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx; or HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx

protocol - The protocol to use when communicating with the module

Throws:

java.lang.UnsupportedOperationException - if using any protocol besides MQTT, if the connection string is missing the "moduleId" field, or if the connection string uses x509

java.lang.IllegalArgumentException - if the provided connection string is null or empty, or if the provided protocol is null

ModuleClient

public ModuleClient(java.lang.String connectionString,
                    IotHubClientProtocol protocol,
                    ClientOptions clientOptions)
             throws java.lang.IllegalArgumentException,
                    java.lang.UnsupportedOperationException

Constructor for a ModuleClient instance.

Parameters:

connectionString - The connection string for the edge module to connect to. Must be in format HostName=xxxx;deviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx; or HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx

protocol - The protocol to use when communicating with the module

clientOptions - The options that allow configuration of the module client instance during initialization

Throws:

java.lang.UnsupportedOperationException - if using any protocol besides MQTT, if the connection string is missing the "moduleId" field, or if the connection string uses x509

java.lang.IllegalArgumentException - if the provided connection string is null or empty, or if the provided protocol is null

ModuleClient

public ModuleClient(java.lang.String hostName,
                    java.lang.String deviceId,
                    java.lang.String moduleId,
                    SasTokenProvider sasTokenProvider,
                    IotHubClientProtocol protocol)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

Parameters:

hostName - The host name of the IoT hub that this client will connect to.

deviceId - The Id of the device containing the module that the connection will identify as.

moduleId - The Id of the module that the connection will identify as.

sasTokenProvider - The provider of all SAS tokens that are used during authentication.

protocol - The protocol that the client will connect over.

ModuleClient

public ModuleClient(java.lang.String hostName,
                    java.lang.String deviceId,
                    java.lang.String moduleId,
                    SasTokenProvider sasTokenProvider,
                    IotHubClientProtocol protocol,
                    ClientOptions clientOptions)

Constructor that allows for the client's SAS token generation to be controlled by the user. Note that options in this client such as setting the SAS token expiry time will throw UnsupportedOperationException since the SDK no longer controls that when this constructor is used.

Parameters:

hostName - The host name of the IoT hub that this client will connect to.

deviceId - The Id of the device containing the module that the connection will identify as.

moduleId - The Id of the module that the connection will identify as.

sasTokenProvider - The provider of all SAS tokens that are used during authentication.

protocol - The protocol that the client will connect over.

clientOptions - The options that allow configuration of the module client instance during initialization.

Method Detail

createFromEnvironment

public static ModuleClient createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel)
                                          throws IotHubClientException

Create a module client instance from your environment variables

Parameters:

unixDomainSocketChannel - the implementation of the UnixDomainSocketChannel interface that will be used if any unix domain socket communication is required. May be null if no unix domain socket communication is required. If this argument is null and unix domain socket communication is required, this method will through an IllegalArgumentException. To check if unix domain socket communication is required for your Edge runtime, check its "IOTEDGE_WORKLOADURI" environment variable. If it is not present, or its value is prefixed with "HTTP" or "HTTPS", then no unix domain socket communication is required, and this argument can be set to null. If its value is present and is prefixed with "unix", then unix domain socket communication will be required, and this argument must not be null.

Returns:

the created module client instance

Throws:

IotHubClientException - if the module client cannot be created

createFromEnvironment

public static ModuleClient createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel,
                                                 IotHubClientProtocol protocol)
                                          throws IotHubClientException

Create a module client instance from your environment variables

Parameters:

unixDomainSocketChannel - the implementation of the UnixDomainSocketChannel interface that will be used if any unix domain socket communication is required. May be null if no unix domain socket communication is required. If this argument is null and unix domain socket communication is required, this method will through an IllegalArgumentException. To check if unix domain socket communication is required for your Edge runtime, check its "IOTEDGE_WORKLOADURI" environment variable. If it is not present, or its value is prefixed with "HTTP" or "HTTPS", then no unix domain socket communication is required, and this argument can be set to null. If its value is present and is prefixed with "unix", then unix domain socket communication will be required, and this argument must not be null.

protocol - the protocol the module client instance will use

Returns:

the created module client instance

Throws:

IotHubClientException - if the module client cannot be created

createFromEnvironment

public static ModuleClient createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel,
                                                 IotHubClientProtocol protocol,
                                                 ClientOptions clientOptions)
                                          throws IotHubClientException

Create a module client instance from your environment variables

Parameters:

unixDomainSocketChannel - the implementation of the UnixDomainSocketChannel interface that will be used if any unix domain socket communication is required. May be null if no unix domain socket communication is required. If this argument is null and unix domain socket communication is required, this method will through an IllegalArgumentException. To check if unix domain socket communication is required for your Edge runtime, check its "IOTEDGE_WORKLOADURI" environment variable. If it is not present, or its value is prefixed with "HTTP" or "HTTPS", then no unix domain socket communication is required, and this argument can be set to null. If its value is present and is prefixed with "unix", then unix domain socket communication will be required, and this argument must not be null.

protocol - the protocol the module client instance will use

clientOptions - The options that allow configuration of the module client instance during initialization

Returns:

the created module client instance

Throws:

IotHubClientException - if the module client cannot be created

sendEvent

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

Synchronously sends a message to to a particular outputName.

Parameters:

message - the message to be sent.

outputName - the outputName to route the message to

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,
                      java.lang.String outputName,
                      int timeoutMilliseconds)
               throws java.lang.IllegalStateException,
                      java.lang.InterruptedException,
                      IotHubClientException

Synchronously sends a message to to a particular outputName.

Parameters:

message - the message to be sent.

outputName - the outputName to route the message to

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.

sendEvent

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

Description copied from class: InternalClient

Synchronously sends a message to IoT hub.

Overrides:

sendEvent in class InternalClient

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.

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

java.lang.IllegalArgumentException

sendEventAsync

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

Sends a message to a particular outputName asynchronously

Parameters:

outputName - the outputName to route the message to

message - the message to send

callback - the callback to be fired when the message is acknowledged by the service

callbackContext - the context to be included in the callback when fired

Throws:

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

sendEventAsync

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

Description copied from class: InternalClient

Asynchronously sends a message to IoT hub.

Overrides:

sendEventAsync in class InternalClient

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.

invokeMethod

public DirectMethodResponse invokeMethod(java.lang.String deviceId,
                                         DirectMethodRequest directMethodRequest)
                                  throws IotHubClientException

Invoke a method on a device

Parameters:

deviceId - the device to invoke a method on

directMethodRequest - the request containing the method to invoke on the device

Returns:

the result of the method call

Throws:

IotHubClientException - if the method cannot be invoked

java.lang.IllegalArgumentException - if deviceId is null or empty

invokeMethod

public DirectMethodResponse invokeMethod(java.lang.String deviceId,
                                         java.lang.String moduleId,
                                         DirectMethodRequest directMethodRequest)
                                  throws IotHubClientException

Invoke a method on a module

Parameters:

deviceId - the device the module belongs to

moduleId - the module to invoke the method on

directMethodRequest - the request containing the method to invoke on the device

Returns:

the result of the method call

Throws:

IotHubClientException - if the method cannot be invoked

java.lang.IllegalArgumentException - if deviceId is null or empty, or if moduleId is null or empty

setMessageCallback

public ModuleClient setMessageCallback(MessageCallback callback,
                                       java.lang.Object context)

Sets the message callback.

This should be set before opening the client. If it is set after opening the client, any messages sent by the service may be missed.

This callback is preserved between reconnection attempts and preserved after re-opening a previously closed client.

Parameters:

callback - the message callback. Can be null.

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

Returns:

itself, for fluent setting.

Throws:

java.lang.IllegalArgumentException - if the callback is null but a context is passed in.

setMessageCallback

public ModuleClient setMessageCallback(java.lang.String inputName,
                                       MessageCallback callback,
                                       java.lang.Object context)

Sets the message callback to be fired when a telemetry message arrives on the specified input channel. All other messages will trigger the default message callback in setMessageCallback(MessageCallback callback, Object context). Any message that triggers this callback will not also trigger the default callback.

Parameters:

inputName - the input name channel to listen for.

callback - the message callback. Can be null.

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

Returns:

this object, for fluent setting