ModuleClient Class

Package:

com.microsoft.azure.sdk.iot.device

• java.lang.Object
• • 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

Constructor Summary

Constructor	Description
ModuleClient(String connectionString, IotHubClientProtocol protocol)	Constructor for a ModuleClient instance. or HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx
ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)	Constructor for a ModuleClient instance. or HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx
ModuleClient(String hostName, String deviceId, 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.
ModuleClient(String hostName, String deviceId, 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.

Method Summary

Modifier and Type	Method and Description
ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel) Create a module client instance from your environment variables
ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel, IotHubClientProtocol protocol) Create a module client instance from your environment variables
ModuleClient	createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel, IotHubClientProtocol protocol, ClientOptions clientOptions) Create a module client instance from your environment variables
DirectMethodResponse	invokeMethod(String deviceId, DirectMethodRequest directMethodRequest) Invoke a method on a device
DirectMethodResponse	invokeMethod(String deviceId, String moduleId, DirectMethodRequest directMethodRequest) Invoke a method on a module
void	sendEvent(Message message)
void	sendEvent(Message message, String outputName) Synchronously sends a message to to a particular outputName.
void	sendEvent(Message message, String outputName, int timeoutMilliseconds) Synchronously sends a message to to a particular outputName.
void	sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext)
void	sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext, String outputName) Sends a message to a particular outputName asynchronously
ModuleClient	setMessageCallback(MessageCallback callback, Object context) Sets the message callback.
ModuleClient	setMessageCallback(String inputName, MessageCallback callback, 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.

Inherited Members

InternalClient.close() InternalClient.DEFAULT_TIMEOUT_MILLISECONDS InternalClient.getConfig() InternalClient.getProductInfo() InternalClient.getTwin() InternalClient.getTwin(int timeoutMilliseconds) InternalClient.getTwinAsync(GetTwinCallback twinCallback, Object callbackContext) InternalClient.getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object callbackContext) InternalClient.open(boolean withRetry) InternalClient.sendEvent(Message message, int timeoutMilliseconds) InternalClient.sendEvents(List<Message> messages) InternalClient.sendEvents(List<Message> messages, int timeoutMilliseconds) InternalClient.sendEventsAsync(List<Message> messages, MessagesSentCallback callback, Object callbackContext) InternalClient.setConnectionStatusChangeCallback(IotHubConnectionStatusChangeCallback callback, Object callbackContext) InternalClient.setOperationTimeout(long timeout) InternalClient.setRetryPolicy(RetryPolicy retryPolicy) InternalClient.subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext) InternalClient.subscribeToDesiredProperties(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, int timeoutMilliseconds) InternalClient.subscribeToDesiredPropertiesAsync(DesiredPropertiesCallback desiredPropertiesCallback, Object desiredPropertiesCallbackContext, SubscriptionAcknowledgedCallback subscriptionAcknowledgedCallback, Object desiredPropertiesSubscriptionCallbackContext) InternalClient.subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext) InternalClient.subscribeToMethods(MethodCallback methodCallback, Object methodCallbackContext, int timeoutMilliseconds) InternalClient.subscribeToMethodsAsync(MethodCallback methodCallback, Object methodCallbackContext, SubscriptionAcknowledgedCallback methodStatusCallback, Object methodStatusCallbackContext) InternalClient.updateReportedProperties(TwinCollection reportedProperties) InternalClient.updateReportedProperties(TwinCollection reportedProperties, int timeoutMilliseconds) InternalClient.updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesCallback reportedPropertiesCallback, Object callbackContext) InternalClient.updateReportedPropertiesAsync(TwinCollection reportedProperties, ReportedPropertiesUpdateCorrelatingMessageCallback reportedPropertiesUpdateCorrelatingMessageCallback, Object callbackContext)

Constructor Details

ModuleClient

public ModuleClient(String connectionString, IotHubClientProtocol protocol)

Constructor for a ModuleClient instance. or

HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx

Parameters:

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

protocol - The protocol to use when communicating with the module

Throws:

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

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

ModuleClient

public ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor for a ModuleClient instance. or

HostName=xxxx;DeviceId=xxxx;SharedAccessKey= xxxx;moduleId=xxxx;HostNameGateway=xxxx

Parameters:

connectionString - The connection string for the edge module to connect to. Must be in format HostName=xxxx;deviceId=xxxx;SharedAccessKey= xxxx;moduleId=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:

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

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

ModuleClient

public ModuleClient(String hostName, String deviceId, 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(String hostName, String deviceId, 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 Details

createFromEnvironment

public static ModuleClient createFromEnvironment(UnixDomainSocketChannel unixDomainSocketChannel)

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)

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)

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

invokeMethod

public DirectMethodResponse invokeMethod(String deviceId, DirectMethodRequest directMethodRequest)

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

IllegalArgumentException - if deviceId is null or empty

invokeMethod

public DirectMethodResponse invokeMethod(String deviceId, String moduleId, DirectMethodRequest directMethodRequest)

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

IllegalArgumentException - if deviceId is null or empty, or if moduleId is null or empty

sendEvent

public void sendEvent(Message message)

Parameters:

message

sendEvent

public void sendEvent(Message message, String outputName)

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:

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

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, String outputName, int timeoutMilliseconds)

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:

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

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.

sendEventAsync

public void sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext)

Parameters:

message

callback

callbackContext

sendEventAsync

public void sendEventAsync(Message message, MessageSentCallback callback, Object callbackContext, String outputName)

Sends a message to a particular outputName asynchronously

Parameters:

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

outputName - the outputName to route the message to

Throws:

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

setMessageCallback

public ModuleClient setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

Parameters:

callback -

the message callback. Can benull 

</code> . </p>

context -

the context to be passed to the callback. Can benull 

</code> .</p>

Returns:

itself, for fluent setting.

Throws:

IllegalArgumentException -

if the callback isnull 

</code> but a context is passed in. </p>

setMessageCallback

public ModuleClient setMessageCallback(String inputName, MessageCallback callback, 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 benull 

</code> . </p>

context -

the context to be passed to the callback. Can benull 

</code> .</p>

Returns:

this object, for fluent setting