Confirmed Delivery

Confirmed Delivery

This tutorial builds on the basic concepts introduced in Persistence with MQTT tutorial and will show you how to properly process publisher acknowledgements. When you receive an acknowledgement for a QoS level 1 message, you have confirmed your message have been properly accepted by the Solace message router and therefore can be guaranteed of no message loss.

Assumptions

This tutorial assumes the following:

  • You are familiar with Solace core concepts.
  • You have access to Solace messaging with the following configuration:
    • Connectivity information for a Solace message-VPN configured for guaranteed messaging support
    • Enabled client username and password
    • Client-profile enabled with guaranteed messaging permissions.
    • Enabled MQTT service

One simple way to get access to Solace messaging quickly is to create a messaging service in Solace Cloud as outlined here. You can find other ways to get access to Solace messaging below.

Goals

The goal of this tutorial is to understand the following:

  1. How to properly handle QoS 1 message acknowledgments on message send

Get Solace Messaging

This tutorial requires access Solace messaging and requires that you know several connectivity properties about your Solace messaging. Specifically you need to know the following:

Resource Value Description
Host String This is the address clients use when connecting to the Solace messaging to send and receive messages. (Format: DNS_NAME:Port or IP:Port)
Client Username String The client username. (See Notes below)
Client Password String The client password. (See Notes below)

There are several ways you can get access to Solace Messaging and find these required properties.

Option 1: Use Solace Cloud

  • Follow these instructions to quickly spin up a cloud-based Solace messaging service for your applications.
  • The messaging connectivity information is found in the service details in the connectivity tab (shown below). You will need:
    • Host:Port (use the MQTT URI)
    • Client Username
    • Client Password

Option 2: Start a Solace VMR

  • Follow these instructions to start the Solace VMR in leading Clouds, Container Platforms or Hypervisors. The tutorials outline where to download and how to install the Solace VMR.
  • The messaging connectivity information are the following:
    • Host: <public_ip> (IP address assigned to the VMR in tutorial instructions)
    • Client Username: sampleUser (can be any value)
    • Client Password: samplePassword (can be any value)

    Note: By default, the Solace VMR “default” message VPN has authentication disabled.

Option 3: Get access to a Solace appliance

  • Contact your Solace appliance administrators and obtain the following:
    • A Solace Message-VPN where you can produce and consume direct and persistent messages
    • The host name or IP address of the Solace appliance hosting your Message-VPN
    • A username and password to access the Solace appliance

Obtaining an MQTT Client Library

Although, you can use any MQTT Client library of your choice to connect to Solace, this tutorial uses the Paho Java Client library. Here are a few easy ways to get the Paho API. The instructions in the Building section assume you’re using Gradle and pulling the jars from maven central. If your environment differs then adjust the build instructions appropriately.

Get the API: Using Gradle

    compile("org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.1.0")

Get the API: Using Maven

<dependency>
  <groupId>org.eclipse.paho</groupId>
  <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
  <version>1.1.0</version>
</dependency>

Connecting a session to Solace messaging

This tutorial builds on the QoS1Producer introduced in Persistence with MQTT. So connect the MqttClient as outlined in the Persistence with MQTT tutorial.

Tracking the delivery of QoS 1 messages

Similar to the QoS1Producer we will publish a QoS 1 message and then wait for an acknowledgement from the broker confirming the message was received and stored.

In MQTT there are two approaches to track the delivery of messages:

  1. Setting an MqttCallback on the client. Once a message has been delivered and stored by Solace messaging, the deliveryComplete(IMqttDeliveryToken) method will be called with delivery token being passed as a parameter.
  2. Using an asynchronous MQTT client and the MqttAsyncClient.publish method, which returns a IMqttToken when the publish call returns. The producer can then use the IMqttToken.waitForCompletion method to block until the delivery has been completed and the broker has acknowledge the message.

For the purpose of this tutorial we choose the first approach and set an MqttCallback on the client. The MqttCallback.deliveryComplete method is implemented here to check if the QoS 1 message has been received and stored by Solace messaging.

// Callback - Anonymous inner-class for receiving msg delivery complete token
mqttClient.setCallback(new MqttCallback() {
    public void messageArrived(String topic, MqttMessage message) throws Exception {
    }

    public void connectionLost(Throwable cause) {
        System.out.println("Connection to Solace broker lost!" + cause.getMessage());
        latch.countDown();
    }

    public void deliveryComplete(IMqttDeliveryToken token) {
        System.out.println("\nMessage was successfully delivered to Solace\n");
        latch.countDown(); // unblock main thread
    }
});

The producer code uses a countdown latch to block the main thread until the MqttCallback.deliveryComplete method has been called.

try {
    latch.await(); // block here until message delivery is completed, and latch will flip
} catch (InterruptedException e) {
    System.out.println("I was awoken while waiting");
}

Summarizing

The full source code for this example is available on GitHub. If you combine the example source code shown above results in the following source:

Getting the Source

Clone the GitHub repository containing the Solace samples.

git clone https://github.com/SolaceSamples/solace-samples-mqtt
cd solace-samples-mqtt

Building

The project uses Gradle. To build, execute the following command.

./gradlew build

This builds all of the Java Samples with OS specific launch scripts. The files are staged in the build/staged directory.

Running the Sample

Run the example from the command line as follows.

$ ./build/staged/bin/confirmedDeliveryProducer <host:port> <client-username> <client-password>
ConfirmedDeliveryProducer initializing...
Connecting to Solace messaging at <host:port>
Connected
Publishing message: Hello world from MQTT!

Message was successfully delivered to Solace

Exiting

When the text “Message was successfully delivered to Solace” is printed on screen, you have confirmed that the published QoS 1 message has been delivered successfully to the broker.

If you have any issues sending and receiving a message, check the Solace community for answers to common issues.