Eclipse Mosquitto Connector for Jolie Programming Language


Sooner or later, the Internet of Things and microservices will be considered the two sides of the same coin. Even if today they are considered as different areas in IT, they both deal with distributed systems where the main differences are represented by the used communication protocols. Microservices, usually deal with HTTP protocol, whereas IoT is built on top of other protocols like MQTT and CoAP.  In this article, we try to approach them together, showing how we built the Ecplipse Mosquitto connector for the Jolie programming language. In the following, we call it the jolie-mosquitto connector.

This article is dedicated to those who are interested in learning how Mosquito works and also to those who are interested in Jolie.

MQTT Protocol and Mosquitto Broker

MQTT ( is an OASIS standard messaging protocol for the Internet of Things (IoT).

It is designed as an extremely lightweight messaging transport for publishing and subscribing, ideal for connecting remote devices with a small code footprint and minimal network bandwidth.
(Official MQTT 3.1.1 specification)

MQTT is a publish/subscribe protocol where three entities are involved:

  • the publisher: the participant which publishes a message;
  • the subscriber: the participant which receives one or more messages;
  • the broker: the participant that is in charge to deliver the messages.

Message Topic

When the publisher sends a message to the broker, it must specify the topic where the message must be published (for example, if the publisher is a sensor that detects the temperature in the bathroom, the topic could be “home/temperature/bathroom”).

The subscriber that is interested in knowing the temperature of the home bathroom will subscribe itself to the topic “home/temperature/bathroom” and it will receive all the messages published on that topic.

Message sorting is performed by the broker.

Eclipse Mosquitto

Eclipse Mosquitto ( is an open source (EPL/EDL licensed) message broker that implements the MQTT protocol versions 5.0, 3.1.1, and 3.1. Since the Jolie interpreter is written in Java, the jolie-mosquitto connector was written in Java too, exploiting the Eclipse Paho library. These libraries are available for different programming languages. Java is one of the possible choices. 

Before showing how the connector works, here we briefly introduce the reader on how to develop a publisher and a subscriber with the Paho library in Java.

The Paho Publisher

In the following we report the Java Paho Publisher:

First of all, the Publisher class constructor must instantiate a new MqttClient by passing two parameters to it:

  •   the URL of the broker
  •   a string that identifies the client id

These parameters are sufficient to instantiate a client even if it is not yet effectively connected to the broker. The connection will be made in the following method start().

The start() method performs the following steps:

  • It creates an options object of the MqttConnectOptions class where it is possible to set all the options needed for the connection.
  • It creates the connection with the broker by calling the connect() method on the mqttClient object, passing the options object as a parameter.
  • It creates an MqttTopic object to indicate the topic where publishing messages.
  • It calls the publish() method on the newly created object by passing an MqttMessage as an argument.

The MqttMessage object accepts three parameters:

  • message: it must be sent as a byte array;
  • qos: Quality of Service (0, 1, 2);
  • retained: the retained flag for the message.

The Paho Subscriber

The Subscriber is instantiated in the same way as the Publisher:

  • Create an MqttClient object
  • Create an MqttConnectOptions object to set the connection options
  • Call the setCallback function on the mqttClient object
  • Connect the client to the Mosquitto broker: client.connect(options)
  • Call the subscribe function on the mqttClient object

As you can see, there are two differences with the Publisher code: 

  • mqttClient.setCallback(new SubscribeCallback()): the parameter required by the setCallback function is an object of the SubscribeCallback class below;
  • mqttClient.subscribe(topic): the topic parameter is a string that identifies the topic you want to subscribe to;

The SubscribeCallback class implements the MqttCallback interface and must override the above methods.

The jolie-mosquitto Connector

In Jolie, there is the possibility to create Javaservices, which are classes written in Java that can be imported and embedded in a Jolie service as they are a service itself. In particular, it is possible to annotate methods of a Javaservice in order to be interpreted as operations by the Jolie interpreter. A Javaservice is always equipped with Jolie interfaces which define the available API of the Javaservice that can be consumed by a Jolie service.

The jolie-mosquitto connector has been created programming a specific Javaservice which fully exploits the Paho library.  The connector is distributed in the form of a .jar file (JolieMosquittoConnector.jar) which also contains the interface written in Jolie (MosquittoInterface.iol).

The jolie-mosquitto Interface

The connector defines three jolie interfaces :

Interface MosquittoInterface deals with the operations necessary for configuring the connector. In particular, there is only one operation named setMosquitto() It permits to set all the parameters needed to instantiate a connection.

Interface MosquittoPublisherInterface define the API for interacting with the connector as a publisher. In particular it defines an operation, called sendMessage(), which permits to send a message to a specific topic and takes care of publishing the desired message into the Mosquitto broker.

Finally, interfaces MosquittoReceiverInterface define the API for interacting with the connector as a subscriber. In particular, it defines the operation receive() to be implemented by the Jolie service in order to process the messages that are going to be received from the broker.

How to Create a Jolie Publisher Exploiting the jolie-mosquitto Connector

In the following code snippet, we show how to configure and use the connector as a publisher inside a Jolie service. In particular, in the scope init of the service, the connector is set to establish a connection with a broker on URL "tcp://localhost:1883" (lines 2-8). Here we suppose to have installed a mosquitto broker previously. The in the scope main, a message ("25°C")  is sent to the topic "home/temperature" (lines 11-17).

It is worth noting that the scope init{}, in Jolie, is executed once at the startup of the service, thus the configuration of the connector is achieved at the start-up of the service. On the contrary, the message sending is programmed within the behavior (scope main{}) where the runtime activities must be defined.

A complete working example for a publisher may be consulted at this link where also ports and interfaces are declared.

How to Create a Jolie Subscriber Exploiting the jolie-mosquitto Connector

In the following code snippet, we show how to configure a subscriber in a Jolie service.

As it happens for the publisher, also for the subscriber the configuration is achieved within the scope init{}. In particular, in this case, the service is configured to be registered as a subscriber on the topic "home/temperature" (parameter subscribe at lines 4-6). In scope main{}, the operation receive() defined into the interface MosquittoReceiverInterface is implemented. It is worth noting that this Jolie service is always listening on the operation receive and every time a message is received, a process which handles it is executed. In particular, in this simple example, the process just print out the message on the console (println@Console( request.message )()).

A complete working example for a subscriber may be consulted at this link where also ports and interfaces are declared.

Have You Ever Implemented a Chat With MQTT?

Although the MQTT protocol, as explained above, is mainly used in the IoT area because of the characteristics that make it particularly suitable for this type of context, to make clear the functioning and the effectiveness of the jolie-mosquitto connector, here we show an example on how to create a chat that uses MQTT for the transmission of messages. Such a choice could appear quite unusual but we think it helps in better understanding how the connector works.

The full example is described here In the following, we provide a brief introduction to it for those who do not want to go deep into the code.

A Web Application for Enabling a GUI

Even if it is an example, in order to make it easy to be used, we decided to create a small Web Application that facilitates users to write and read messages to/from the chat. To do this we exploited a Web Server written in Jolie called Leonardo. Each participant needs to run its own local web application connected to the MQTT broker. 

In the following picture, we report the architecture of the system when two participants intend to chat together.

Each application is composed by three main components: 

  • The Web Server Leonardo leonardo.ol
  • A Frontend service (frontend.ol) which implements the business logics of the API exposed to the web GUI. 
  • The jolie-msquitto connector that is charge to communicate with the mqtt broker.

All the services are embedded with a unique Java Virtual Machine. In Jolie indeed, it is possible to deploy a set of services within the same Java Virtual Machine by exploiting the primitive embedding.

In particular, the Web Server leonardo.ol exposes an inputPort (localhost:16000) where it is listening for requests from the browser. Leonardo also internally forwards the incoming requests to the front-end service operating a message transformation from a json format to a Jolie value. As an example, it receives the messages written into an <input> tag in the web GUI and sends them to the mosquitto connector. The service frontend.ol also receives the messages that arrive from the broker Mosquitto through the connector. It is worth noting that in this case, the service frontend plays both the roles of publisher and subscriber. The frontend.ol service, finally, embeds the jolie-mosquitto JavaService connector. 

For the sake of brevity here, we comment the behavior of the service frontend, which contains all the logic behind the chat. There are four operations implemented:

  • receive (request) : it is a OneWay operation that is invoked by the Mosquitto broker through the MosquittoReceiverInteface interface every time a message is published on the topic where the service has been registered as a subscriber. In this example, the received message is a JSON that is converted with getJsonValue operation and then saved in a global variable called messageQueue.
  • getChatMessages (GetChatMessagesRequest)(GetChatMessagesResponse): it is a RequestResponse operation that is invoked periodically from the html page of the chat. In this example all the messages present in the messageQueue are inserted in the Response that is sent to the html page that will take care of visualizing them. Finally, the global variable messageQueue is cleaned.
  • sendChatMessage (messageRequest)(response): it is a RequestResponse operation that is invoked by the publisher every time it wants to publish a message on the broker Mosquitto. In this example a json type message is created containing the Publisher’s username and the message to send. A request is then created containing the topic on which you want to publish the message and the message itself. Finally, through the sendMessage@Mosquitto operation the message is sent to the Mosquitto broker.
  • setUsername (usernameRequest)(usernameResponse): is a simple operation that allows to associate a username to the message sent from a service.

In the following, we briefly report the sequence chart diagram of the chat example.


In this article, we discussed a connector for Eclispse Mosquitto to be used when programming microservices in Jolie. We described the Java Paho library that is at the basis of the connector and we show how a Javaservice has been created on top of it for allowing its usage inside a Jolie service. Finally, we present a jolie example that implements a chat that uses Mosquitto for sending and receiving messages. 

IoT and microservices are very important topics that are often addressed together. Here we explain how to exploit an MQTT connector in a fully service-oriented programming paradigm like that offered by Jolie. The main idea is to always use the same programming paradigm for facing different distributed scenarios in order to simplify the development and the maintenance of a microservice/IoT application.

This UrIoTNews article is syndicated fromDzone