MQTT over TLS/SSL

You can test the MQTT interface over TLS/SSL using a client. This sample client uses Eclipse Paho Java Client, a library written for developing applications that run on the JVM or other Java compatible platforms, such as Android.

The MQTT client uses the MqttClient API to provide asynchronous service. In this case, it notifies completed activities as registered callbacks.

Before you begin

This sample client uses JSON web token (JWT) for verification. Make sure to configure the JWT behavior in your property and store the client ID.

Before using this client, you may want to check useful related links:

Downloading and adding dependencies

To start using this client, add these dependencies to your pom.xml file:

<repositories>
   <repository>
       <id>Eclipse Paho Repo</id>
       <url>https://repo.eclipse.org/content/repositories/paho-releases/</url>
   </repository>
</repositories>
...
<dependencies>
   <dependency>
       <groupId>org.eclipse.paho</groupId>
       <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
       <version>1.2.5</version>
   </dependency>
</dependencies>

Connecting and publishing messages

Use this Java code snippet (compiles with Java 8) as a basic sample to connect to a server and publish a message using the MqttClient synchronous API:

public class MqttService {

   private MqttClient client;
   private final MqttConnectOptions options;
   private final MqttCallback onMessageCallback;

   public MqttService(MqttConnectOptions options, MqttCallback onMessageCallback) {
       this.options = options;
       this.onMessageCallback = onMessageCallback;
   }

   public void connect(String broker, String clientId, String userName) throws MqttException {
       options.setUserName(userName);
       client = new MqttClient(broker, clientId, new MemoryPersistence());
       client.setCallback(onMessageCallback);
       client.connect(options);
   }

   public void subscribe(String topic, int qos) throws MqttException {
       if (isClientPresent()) {
           client.subscribe(topic, qos);
       }
   }

   public void publish(String topic, String message, int qos) throws MqttException {
       final MqttMessage content = new MqttMessage(message.getBytes());
       content.setQos(qos);

       if (isClientPresent()) {
           client.publish(topic, content);
       }
   }

   private boolean isClientPresent() {
       if (client == null) {
           throw new IllegalStateException("You need to connect to the broker first");
       }
       return true;
   }

Provide the MQTT connection options as a first argument in the constructor. Note that any string value for userName and specific mqttVersion (3.1.1) are required:

MqttConnectOptions options = new MqttConnectOptions();
options.setUserName(userName); // Sets the username for the connection. This can be any string value.
options.setPassword(token.toCharArray());
options.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1); // Sets the version of the MQTT protocol. This must be version 3.1.1.
options.setCleanSession(true);

For the onMessageCallback argument, you should provide an implementation of the MqttCallback class that defines which asynchronous events notify the API. Available methods you can implement include connectionLost (notify when the connection to the server is lost), deliveryComplete (when delivery for a message completes and all acknowledgments are received), and messageArrives (when a message arrives from the server).

Edit the sample and add code to connect to the MQTT service over a client:

MqttService service = new MqttService(options, onMessageCallback);
service.connect(broker, clientId, userName);
service.publish(topic, message, 1);
service.subscribe(topic, 1);

For clientID, set the same value you passed earlier in the JWT token, which should be your unique personal client ID. If another client connects with the same clientID, the original connection breaks.

Replace broker with a path value in the ssl://hostname:8883 format, where the hostname matches that of your configured property. See Configure the IoT Edge Connect property.

You can find more detailed examples in the org.eclipse.paho.sample.mqttv3app directory of the library source or package documentation.