Confirmed Delivery
4 Minute Read
This tutorial builds on the basic concepts introduced in Persistence with Queues 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:
- How to properly handle QoS 1 message acknowledgments on message send
Get Solace Messaging
This tutorial requires access Solace PubSub+ messaging and requires that you know several connectivity properties about your Solace messaging. Specifically you need to know the following:
Resources | Value | Description |
---|---|---|
Host | String | This is the address clients use when connecting to the PubSub+ messaging to send and receive messages. (Format: DNS_NAME:Port or IP:Port ) |
Message VPN | String | The PubSub+ message router Message VPN that this client should connect to. |
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 PubSub+ Messaging and find these required properties.
Option 1: Use PubSub+ Cloud
-
Follow these instructions to quickly spin up a cloud-based PubSub+ 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 SMF URI)
- Message VPN
- Client Username
- Client Password
Option 2: Start a PubSub+ Software
-
Follow these instructions to start the PubSub+ Software in leading Clouds, Container Platforms or Hypervisors. The tutorials outline where to download and how to install the PubSub+ Software.
-
The messaging connectivity information are the following:
-
Host: <public_ip> (IP address assigned to the VMR in tutorial instructions)
-
Message VPN: default
-
Client Username: sampleUser (can be any value)
-
Client Password: samplePassword (can be any value)
Note: By default, the PubSub+ Software "default" message VPN has authentication disabled.
-
Option 3: Get access to a PubSub+ Appliance
-
Contact your PubSub+ appliance administrators and obtain the following:
- A PubSub+ 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:
- Setting an
MqttCallback
on the client. Once a message has been delivered and stored by Solace messaging, thedeliveryComplete(IMqttDeliveryToken)
method will be called with delivery token being passed as a parameter. - Using an asynchronous MQTT client and the
MqttAsyncClient.publish
method, which returns aIMqttToken
when the publish call returns. The producer can then use theIMqttToken.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.