ModuleClient Class

  • Reference
Package:
com.microsoft.azure.sdk.iot.device
Maven Artifact:
com.microsoft.azure.sdk.iot:iot-device-client:1.30.1

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.
ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions)

Constructor for a ModuleClient instance.
ModuleClient(String connectionString, IotHubClientProtocol protocol, String publicKeyCertificate, boolean isCertificatePath, String privateKey, boolean isPrivateKeyPath)

Deprecated

For x509 authentication, use ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Create a module client instance that uses x509 authentication.
ModuleClient(String connectionString, IotHubClientProtocol protocol, SSLContext sslContext)

Deprecated

For x509 authentication, use ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Create a module client instance that uses the provided SSLContext for SSL negotiation.
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.
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.

Method Summary

Modifier and Type Method and Description
void <Type1,Type2>startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.PropertyCallBack<Type1,Type2> genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the module twin.
static ModuleClient createFromEnvironment()

Create a module client instance from your environment variables
static ModuleClient createFromEnvironment(IotHubClientProtocol protocol)

Create a module client instance from your environment variables
static ModuleClient createFromEnvironment(IotHubClientProtocol protocol, ClientOptions clientOptions)

Create a module client instance from your environment variables
void getTwin()

Retrieves the twin's latest desired properties
MethodResult invokeMethod(String deviceId, MethodRequest methodRequest)

Invoke a method on a device
MethodResult invokeMethod(String deviceId, String moduleId, MethodRequest methodRequest)

Invoke a method on a module
void sendEventAsync(Message message, IotHubEventCallback callback, Object callbackContext)

Asynchronously sends an event message to the IoT Hub.
void sendEventAsync(Message message, IotHubEventCallback 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.
void startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertiesCallback genericPropertiesCallBack, Object genericPropertyCallBackContext)

Starts the module twin.
void startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the module twin.
void subscribeToMethod(DeviceTwin.DeviceMethodCallback methodCallback, Object methodCallbackContext, IotHubEventCallback methodStatusCallback, Object methodStatusCallbackContext)

Subscribes to method invocations on this module.

Methods inherited from InternalClient

close closeNow getConfig getProductInfo isMultiplexed open registerConnectionStatusChangeCallback sendEventAsync sendEventBatchAsync sendReportedProperties sendReportedProperties sendReportedProperties sendReportedProperties setAsMultiplexed setOperationTimeout setOption setProxySettings setRetryPolicy subscribeToDesiredProperties subscribeToTwinDesiredProperties

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

ModuleClient

public ModuleClient(String connectionString, IotHubClientProtocol protocol)

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:

ModuleClientException - if an exception is encountered when parsing the connection string
java.lang.IllegalArgumentException - if an exception is encountered when parsing the connection string
java.lang.UnsupportedOperationException - if an exception is encountered when parsing the connection string
java.net.URISyntaxException - if an exception is encountered when parsing the connection string

ModuleClient

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

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:

ModuleClientException - if an exception is encountered when parsing the connection string
java.lang.IllegalArgumentException - if an exception is encountered when parsing the connection string
java.lang.UnsupportedOperationException - if an exception is encountered when parsing the connection string
java.net.URISyntaxException - if an exception is encountered when parsing the connection string

ModuleClient


public ModuleClient(String connectionString, IotHubClientProtocol protocol, String publicKeyCertificate, boolean isCertificatePath, String privateKey, boolean isPrivateKeyPath)

Deprecated

For x509 authentication, use ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Create a module client instance that uses x509 authentication.

Note! Communication from a module to another EdgeHub using x509 authentication is not currently supported and the service will always return "UNAUTHORIZED"

Communication from a module directly to the IotHub does support x509 authentication, though.

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 communicate with
publicKeyCertificate - The PEM formatted string for the public key certificate or the system path to the file containing the PEM.
isCertificatePath - 'false' if the publicKeyCertificate argument is a path to the PEM, and 'true' if it is the PEM string itself,
privateKey - The PEM formatted string for the private key or the system path to the file containing the PEM.
isPrivateKeyPath - 'false' if the privateKey argument is a path to the PEM, and 'true' if it is the PEM string itself,

Throws:

ModuleClientException - If the connString cannot be parsed
java.net.URISyntaxException - If the connString cannot be parsed

ModuleClient


public ModuleClient(String connectionString, IotHubClientProtocol protocol, SSLContext sslContext)

Deprecated

For x509 authentication, use ModuleClient(String connectionString, IotHubClientProtocol protocol, ClientOptions clientOptions) and provide an SSLContext instance in the ClientOptions instance. For a sample on how to build this SSLContext, see this code which references a helper class for building SSLContext objects for x509 authentication as well as for SAS based authentication. When not using this deprecated constructor, you can safely exclude the Bouncycastle dependencies that this library declares. See this pom.xml for an example of how to do this.

Create a module client instance that uses the provided SSLContext for SSL negotiation.

Parameters:

connectionString - The connection string for the edge module to connect to. May be an x509 connection string or a SAS connection string. If it is an x509 connection string, the provided SSLContext will be used for x509 authentication
protocol - The protocol to communicate with
sslContext - the ssl context that will be used during authentication. If the provided connection string does not contain SAS based credentials, then the sslContext will be used for x509 authentication. If the provided connection string does contain SAS based credentials, the sslContext will still be used during SSL negotiation.

Throws:

ModuleClientException - if the hostname in the connection string is not a valid URI
java.net.URISyntaxException - if the hostname in the connection string is not a valid URI

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

<Type1,Type2>startTwin

public void startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.PropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the module twin. This module client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this module client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this module client to receive the full desired properties set, and the PATCH will cause this module client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.
deviceTwinStatusCallbackContext - the context to be passed to the status callback. Can be null.
genericPropertyCallBack - the PropertyCallBack callback for providing any changes in desired properties. Cannot be null.
genericPropertyCallBackContext - the context to be passed to the property callback. Can be null.

Throws:

java.io.IOException - if the callback is null
java.lang.IllegalArgumentException - if the callback is null
java.lang.UnsupportedOperationException - if the callback is null

createFromEnvironment

public static ModuleClient createFromEnvironment()

Create a module client instance from your environment variables

Returns:

the created module client instance

Throws:

ModuleClientException - if the module client cannot be created

createFromEnvironment

public static ModuleClient createFromEnvironment(IotHubClientProtocol protocol)

Create a module client instance from your environment variables

Parameters:

protocol - the protocol the module client instance will use

Returns:

the created module client instance

Throws:

ModuleClientException - if the module client cannot be created

createFromEnvironment

public static ModuleClient createFromEnvironment(IotHubClientProtocol protocol, ClientOptions clientOptions)

Create a module client instance from your environment variables

Parameters:

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:

ModuleClientException - if the module client cannot be created

getTwin

public void getTwin()

Retrieves the twin's latest desired properties

Throws:

java.io.IOException - if the iothub cannot be reached

invokeMethod

public MethodResult invokeMethod(String deviceId, MethodRequest methodRequest)

Invoke a method on a device

Parameters:

deviceId - the device to invoke a method on
methodRequest - the request containing the method to invoke on the device

Returns:

the result of the method call

Throws:

ModuleClientException - if the method cannot be invoked
java.lang.IllegalArgumentException - if the method cannot be invoked

invokeMethod

public MethodResult invokeMethod(String deviceId, String moduleId, MethodRequest methodRequest)

Invoke a method on a module

Parameters:

deviceId - the device the module belongs to
moduleId - the module to invoke the method on
methodRequest - the request containing the method to invoke on the device

Returns:

the result of the method call

Throws:

ModuleClientException - if the method cannot be invoked
java.lang.IllegalArgumentException - if the method cannot be invoked

sendEventAsync

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

Asynchronously sends an event message to the IoT Hub.

Overrides:

ModuleClient.sendEventAsync(Message message, IotHubEventCallback callback, Object callbackContext)

Parameters:

message
callback
callbackContext

Throws:

java.lang.IllegalArgumentException

sendEventAsync

public void sendEventAsync(Message message, IotHubEventCallback 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:

java.lang.IllegalArgumentException - if the provided outputName is null or empty

setMessageCallback

public ModuleClient setMessageCallback(MessageCallback callback, Object context)

Sets the message callback.

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.

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 be null.
context - the context to be passed to the callback. Can be null.

Returns:

this object, for fluent setting

startTwin

public void startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertiesCallback genericPropertiesCallBack, Object genericPropertyCallBackContext)

Starts the module twin. This module client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this module client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this module client to receive the full desired properties set, and the PATCH will cause this module client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.
deviceTwinStatusCallbackContext - the context to be passed to the status callback. Can be null.
genericPropertiesCallBack - the TwinPropertyCallBack callback for providing any changes in desired properties. Cannot be null.
genericPropertyCallBackContext - the context to be passed to the property callback. Can be null.

Throws:

java.io.IOException - if the callback is null
java.lang.IllegalArgumentException - if the callback is null
java.lang.UnsupportedOperationException - if the callback is null

startTwin

public void startTwin(IotHubEventCallback deviceTwinStatusCallback, Object deviceTwinStatusCallbackContext, DeviceTwin.TwinPropertyCallBack genericPropertyCallBack, Object genericPropertyCallBackContext)

Starts the module twin. This module client will receive a callback with the current state of the full twin, including reported properties and desired properties. After that callback is received, this module client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed. IoT Hub supports a PUT and a PATCH on the twin. The PUT will cause this module client to receive the full desired properties set, and the PATCH will cause this module client to only receive the updated desired properties. Similarly, the version of each desired property will be incremented from a PUT call, and only the actually updated desired property will have its version incremented from a PATCH call. The java service client library uses the PATCH call when updated desired properties, but it builds the patch such that all properties are included in the patch. As a result, the device side will receive full twin updates, not partial updates. See PUT and PATCH

Parameters:

deviceTwinStatusCallback - the IotHubEventCallback callback for providing the status of Device Twin operations. Cannot be null.
deviceTwinStatusCallbackContext - the context to be passed to the status callback. Can be null.
genericPropertyCallBack - the TwinPropertyCallBack callback for providing any changes in desired properties. Cannot be null.
genericPropertyCallBackContext - the context to be passed to the property callback. Can be null. *

Throws:

java.io.IOException - if the callback is null
java.lang.IllegalArgumentException - if the callback is null
java.lang.UnsupportedOperationException - if the callback is null

subscribeToMethod

public void subscribeToMethod(DeviceTwin.DeviceMethodCallback methodCallback, Object methodCallbackContext, IotHubEventCallback methodStatusCallback, Object methodStatusCallbackContext)

Subscribes to method invocations on this module. This does not include method invocations on the device the module belongs to

Parameters:

methodCallback - Callback on which device methods shall be invoked. Cannot be null.
methodCallbackContext - Context for device method callback. Can be null.
methodStatusCallback - Callback for providing IotHub status for device methods. Cannot be null.
methodStatusCallbackContext - Context for device method status callback. Can be null.

Throws:

java.io.IOException - if called when client is not opened.
java.lang.IllegalArgumentException - if called when client is not opened.

Applies to