Getting Started Guide

MQTT.Cool requires a Java Virtual Machine. You can use either OpenJDK or Oracle Java Platform, Standard Edition (either the Server JRE or the JDK). Minimum supported Java version is 8, but newer versions are recommended.

Download the latest MQTT.Cool package for your operating system.

On Mac or Unix-based systems, unpack the tarball:

The mqtt.cool directory will be created.

On Windows systems, extract the mqtt.cool_X_Y_Z_YYYYMMDD.zip archive using your preferred tool into a directory of your choice (a short base path is recommended, e.g., "C:\"). The mqtt.cool directory will be created.

Modify a few factory settings of the MQTT.Cool configuration:

Before starting MQTT.Cool, a target MQTT broker to which to connect should be up and running, otherwise no client connections can be accepted.

MQTT.Cool comes with a set of predefined configurations for connecting with local MQTT server instances as well as with the most common publicly accessible brokers. To provide a new custom configuration, open the mqtt.cool/conf/brokers_configuration.xml file and add a set of entries similar to the following:

As you can see, the connection parameters for a specific configuration share a common prefix, which is the connection alias to be used by the clients to specify the MQTT broker to use.

Now, start your MQTT broker or ensure it is already running.

To launch MQTT.Cool:

To verify whether the server has started correctly, open your browser to http://localhost:8080 (change the port according to Section 1.3.3.1, “Choose TCP ports”) and watch the Welcome page:

From the Welcome page, you can immediately start using MQTT.Cool by launching the Test Client, a very simple and linear GUI (based on the MQTT.Cool API) through which you can test the interaction between the MQTT.Cool server and MQTT brokers.

By providing clear and separate sections, aimed at offering an enjoyable user experience, the Test Client allows you to perform all the common operations you may expect from any MQTT client tool, such as:

The Test Client is a really handy tool you may take benefit of every time you find yourself:

A very simple and fast way to play with MQTT.Cool is running the official Docker image:

Once launched the container, point the browser to http://localhost:8080 to check the Welcome Page.

It is possible to customize practically every aspect of the running instance. In the example below, a specific configuration file is provided to the container:

You may also want to create your own image by deriving the official one. The following is a very basic Dockerfile that simply overrides the configuration files with your customized versions (which must be placed in the same folder in this example).

To build the image, launch the docker build command:

Then run it with:

See the official page on Docker Hub to get more details.

First of all, we need an up and running MQTT broker to which clients can connect for messages exchange.

To keep things simple, let’s configure a broker on the same machine on which MQTT.Cool has been already installed so that no particular network setup will be needed to make the two servers talk to each other.

We suggest using Mosquitto, as it is very easy to configure and run, besides being one of the most popular and widely used open source MQTT brokers.

Download and install the binary package according to your system.

As the default configuration is OK for our goals (no authentication required and service will listen on default TCP port 1883), simply start the broker:

After having configured and started the broker, you need to ensure that MQTT.Cool can contact it upon a connection request coming from any client.

MQTT.Cool comes with a set of predefined configurations for connecting with local MQTT server instances as well as with the most common publicly accessible brokers. They are defined in the mqtt.cool/conf/brokers_configuration.xml file through sets of entries similar to the following:

Basically, the connection parameters for a specific configuration share a common prefix, which is the connection alias to be used by the clients to specify the MQTT broker to use More details on this will be provided in Section 2.1, “Static Lookup”.

For the exercise, the following predefined configuration allows MQTT.Cool to connect to the local Mosquitto server; therefore, there is no need to change default settings:

As stated, to simulate and publish telemetry information, we will lean on a Java client application that is based on the Eclipse Paho Java Client, a widely used MQTT client library for the JVM.

Let’s start with the code snippet relative to the application entry point:

The task is implemented through an instance of the Feed class, which produces fake data and sends them to the designated MQTT topics. Below the code snippet for the run method:

To recap, here is how the full MQTT client application code should look like:

From the development folder under which you are going to build the feed example, execute the following easy steps (shown for a Linux system):

From now on, the messages are periodically published to the MQTT broker.

Let’s focus now on the most exciting part, which will lead us to run our MQTT.Cool JavaScript client application!

Once again, because we aim to make our life easier, we are going to embed the client code into a very simple HTML page as follows:

The body element simply contains the two div objects referenced by the JavaScript code and periodically rendered with published telemetry data. Their identifiers match the relevant part of the topics (e.g., telemetry/<metric>), so that it is trivial to dispatch any message payload to its pertinent visual object.

Finally, load the HTML page into the web browser, which should display something similar to the following:

Just two last notes:

Final recommendation: enjoy MQTT messaging with MQTT.Cool!

Static Lookup may also be extended by a plugged Hook, which may be programmed to resolve the provided connection alias as will be further detailed in Section 4.2.5.1, “Providing Broker Configuration”: when no configurations exist in brokers_configuration.xml, MQTT.Cool will ask the Hook to supply a valid one.

The clients have the opportunity to customize the following connection settings, which will override the ones defined on the server side:

The Clean Session flag is always provided by clients.

As you have seen so far, Static Lookup offers several major benefits:

As for Static Lookup, the clients may specify other connection settings:

Once again, the Clean Session flag is provided only on the client side.

By employing Dynamic Lookup, you will lose all the benefits described for Static Lookup; however, some use cases could take advantage of this feature, for example:

Before starting to develop your web application, you should evaluate the most appropriate deployment architecture to employ.

Even though MQTT.Cool comes with an internal web server that can serve static content, normally this solution should be taken into consideration only for the purpose of test and demo, as it allows to easily run out-of-the-box prototypes and samples.

On the contrary, for production scenarios, it is highly recommended to deploy an architecture similar to the following:

where an external web server (e.g., Apache, nginx, IIS, or any other server of your choice) is used to supply web resources, whereas MQTT.Cool is in charge of supporting the end-to-end communication between clients and the MQTT broker; moreover, both the MQTT.Cool server and the web server are deployed together in the DMZ network while the MQTT broker is protected by a second firewall. Of course, both servers can be clustered for fail-over and load balancing.

Let’s explore now how to use the offered SDKs.

You have different options to install the JavaScript library for Web Clients, with or without npm:

The library implements the UMD pattern, which means that its API objects can be exposed indifferently as:

This way, the same JavaScript file can be used according to your preferred development style, as will be shown in the following sub-sections.

Even if technically compatible with any CommonJS environment like Node.js, the library has been expressly designed to work in the context of a web browser. But don’t worry: as already anticipated, a dedicated SDK is available!

The client library transparently implements multiplexed MQTT channels as all the MqttClient instances created from the same MQTTCoolSession object establish a new channel over the same MQTT.Cool connection.

Though they are combined into a common physical connection, multiplexed channels enable separate and isolated end-to-end communications, thus allowing you to:

By leveraging multiplexed channels, you can make MqttClient instances connect to single or multiple brokers. The following picture shows an example where three MttClient instances are establishing independent channels to set up their own end-to-end connection to the target MQTT broker.

Multiplexing is a very efficient way to manage the communications with the MQTT.Cool server and MQTT brokers. On the other hand, there could be circumstances where this is not the desired behavior; for example, if you want to avoid that an MQTT.Cool connection outage affects all engaged MQTT channels.

To prevent a channel from getting multiplexed, you have to initiate every single connection only from MqttClient instances with each one generated by separate MQTTCoolSession objects, thus enforcing each MQTT.Cool connection to host a single MQTT channel.

Let’s focus now on broker connections. Based on the way they are managed on the server side, an end-to-end connection can be of two types, dedicated or shared, as will be detailed in the next two sections.

For each MqttClient that is provided with a valid client identifier at the time of creation through MQTTCoolSession, MQTT.Cool establishes on the server side a dedicated broker connection (as defined previously) devoted to carrying all the messages to be exchanged with the target MQTT server.

In the following deployment example, four dedicated broker connections are activated to support the same number of MqttClient instances (and relative MQTT channels).

Because each broker connection uses the client identifier as sent by the client, if another MqttClient object or any other generic external MQTT client connects to the same broker using an identical client identifier, the connection will be closed as per the MQTT Protocol Specifications.

By employing a dedicated end-to-end connection, MQTT.Cool guarantees full support of the following features:

A shared end-to-end connection is realized when MQTT.Cool holds a single broker connection that will be shared among all those MqttClient instances (even hosted on different network locations) with the following common characteristics:

From the following diagram, you can see how the MQTT.Cool server logically joins together separate MQTT channels targeted to the same MQTT broker into single broker connections, namely:

By exploiting this mechanism, MQTT.Cool drastically reduces the number of newly created MQTT connections to the broker, with the purpose of optimizing the server side resources. From the above example, the number of physical MQTT connections required to serve all the MqttClient instances is halved with respect to the dedicated scenario.

Furthermore, all the subscriptions to the same topic filter will be logically merged into one single MQTT subscription, which is actually activated on the shared broker connection. This enables offloading the fan-out to MQTT.Cool, as it will be responsible for propagating messages flowing on the MQTT channel up to all subscribing clients. We define such kind of subscriptions fanout subscriptions.

The picture below shows an example in which a message targeted to cool/topic is initially published by an external MQTT client to the MQTT broker.

MQTT.Cool receives the message over the shared broker connection established to support the MqttClient instances 1, 2, and 3 (all connected to the same broker), and also over the dedicated one, which has been activated to allow communications to/from the MqttClient instance 4. The message is finally relayed to all clients. In the case of a shared connection, instead of sending a copy of the message to each connected client individually, the MQTT broker has delegated such heavy task to MQTT.Cool, thus releasing its own resources to serve other clients and dispatch other messages.

Lastly, before using a shared connection, take into consideration the following constraints:

If you start a dedicated connection requiring a persistent session, then its related data are normally saved on the default local storage, which is based on:

In addition, you also have the option to supply a custom persistence layer by setting the storage connection option with an implementation of the MqttStorage interface:

Before opening a connection, you might want to provide the onConnectionLost callback function in order to properly manage the event of an end-to end connection lost. The callback has to be set on the MqttClient instance:

An end-to-end connection could be lost for one of the following reasons:

Each type of disconnection generates its own error code and description, which are embedded in the responseObject passed to the callback.

After losing the connection, the MqttClient instance switches to the disconnected status from which it would be possible to start a new connection.

If you want to be notified about the outcome of a message delivery, then all you need is to set on the MqttClient instance a pair of callback functions.

In particular, onMessageNotAuthorized will be triggered in the case of any authorization issue raised by the plugged Hook once the message is received by MQTT.Cool (as will be described in Section 4.2.6, “Authorizing Message Publishing”):

while onMessageDelivered will be invoked once the delivery process completes:

In the latter case, successful completion of the delivery process depends on several factors:

As allowed by the MQTT Protocol Specifications, the provided topic filter can also contain special wildcard characters so that you can subscribe to multiple topics at once. In particular, you can use Multi-level wildcard, Single level wildcard, or even mix them:

By means of subscribe options, you can specify several parameters that allow you to govern how the subscription has to be requested to the broker.

A message sent from the MQTT broker reaches MqttClient through the mediation of MQTT.Cool; once arrived, the invocation of onMessageArrived is based on the following factors, similarly to what happens for onMessageDelivered:

In particular:

The session state of an MqttClient instance obviously depends on the current end-to-end connection type:

By setting the onReconnectionStart callback function on the MqttClient instance, you will be notified when the MQTT.Cool connection has been interrupted and an attempt to re-establish it has started:

The onReconnectionStart callback will be invoked indefinitely until one of the following events occurs:

which is also the recommended pattern to stop definitively any reconnection attempt. In this case, there will not be any further chances to resume the state of an MqttClient instance that is without a persistent session.

As soon as the MQTT.Cool connection is restored, the MqttClient instance and the MQTT.Cool server cooperate silently in order to fully restore the whole end-to-end connection, whereupon the session state will be resumed as follows:

In order to be notified when the reconnection process successfully completes, provide the MqttClient instance with the onReconnectionComplete callback as follows:

The MQTT.Cool SDK for Java Hooks provides an open source API through which you can easily develop any Hook.

Because the API is available from the Maven Central Repository, add the following dependency to your pom.xml to set up your development environment :

Basically, an MQTT.Cool Hook is implemented through a user defined Java class, which implements the MQTTCoolHook interface.

Such an interface exposes a set of methods that may be categorized as follows:

As will be shown in the subsequent sections, you might want to supply a specific behavior only to those methods in which you are actually interested, whereas you may provide a fake implementation for all others. Furthermore, SDK includes the SimpleCoolHook base class, which is a skeletal implementation of the interface meant to be extended to make it easier to provide a full implementation of a custom Hook.

The SimpleCoolHook class provides the following default behaviors for each specific method category:

Let’s start writing a simple Hook, which will help you to grasp the core concepts needed to implement your own extensions.

A Hook is loaded during the MQTT.Cool initialization process. If you need to run some setup logic, then you have to override the init method:

The configDir parameter is the <MQTT.COOL_HOME>/hook directory, where you can put any resource you may need to initialize the Hook (for example, configuration files).

If you want to intercept a new session started by the client (as detailed in Section 3.4, “The MQTT.Cool Connection Pattern”), then you have to override the canOpenSession method:

On the basis of the parameter values, you could apply your own security policies to authorize the session. You could also contact an external service (like databases or LDAP servers) to authenticate the user who is requesting to connect to MQTT.Cool. The following example shows a straight user ID/password-based authentication:

As you have seen in Section 3.5, “The MQTTCoolSession Interface”, the onConnectionFailure callback is invoked in the case of any authorization issue:

In particular, the errorType parameter is set to the string UNAUTHORIZED_SESSION, which is the reserved value for any authorization issue, whereas the remaining parameters are undefined. This is what happens when the Hook denies authorization to open a new session by returning the false value (as in the example above). Nevertheless, you are allowed to throw a HookException with detailed code and message, which will be forwarded, respectively, as errorCode and errorMessage parameters to the client, thus enabling the latter to distinguish the kind of problem by looking at them.

More generally, from any Authorization Request method you have two options for reporting an issue to the client:

The following code snippet modifies the previous example; this time, a HookException is thrown to signal specific failure conditions, although a Boolean value is still returned to indicate whether the provided password matches the stored one.

On the client side, now you can decide how to react on the basis of the error details, sent as specified inside the raised HookException:

The following diagram shows the sequence of messages and events on both the client side and the server side during the creation of a session.

As shown in Section 3.4, “The MQTT.Cool Connection Pattern”, after having established a connection to MQTT.Cool, a client might want to connect to a specific MQTT broker. By overriding the canConnect method, you can intercept and authorize the connection request:

For example, you could check the credentials (provided in the connection options) before being passed to the broker, thus enabling you to extend the latter with a further layer of authentication logic if the native one does not fully satisfy your security needs (or even in the case where the broker does not implement any authentication itself).

The following code snippet shows you an example of a very specific authorization policy, which allows unauthenticated users to access to the MQTT broker on the condition that they establish a dedicated connection without managing session persistence:

Inspecting the connectOptions parameter helps you to easily accomplish the task as it contains the options actually being used by the MQTT.Cool server to connect to the target MQTT broker. See the MqttConnectOptions API reference for more detailed information.

On the client side, you will be notified about the raised authorization issue by means of the related callback function as described in Section 3.7, “Specifying Connection Options”:

Similarly to the onConnectionFailure callback, here the responseObject parameter is passed only when a HookException has been thrown on the server side, thus allowing you to differentiate the kind of problem by looking at the errorCode and errorMessage properties, which reflects, respectively, the code and the message as embedded into the exception.

The following sequence diagram shows the interactions required to establish an authorized end-to-end connection between the client and the target MQTT broker.

Any MQTT message sent from the client can be checked through the canPublish method before being delivered to the target MQTT broker:

The message contents can be inspected by looking at the message parameter, which you could use to apply your own authorization logic. See the MqttMessage API reference for more detailed information.

As an example, if your broker does not support QoS 2 messages, then you might prevent them from being sent; likewise, you could block all the messages targeted to some specific topic names:

As anticipated in Section 3.9.1, “Message Delivery Notification”, on the client side you can leverage the onMessageNotAuthorized callback function to be informed about any authorization issue:

Once again, the responseObject parameter is provided only in the case of the HookException thrown on the server side.

The diagram below shows an example of QoS 1 message publishing checked by the Hook, where the activated connection type (shared or dedicated) does not involve session persistence; therefore, on the client side, the message delivery notification occurs once the delivery protocol has been completed on the server side.

Similarly to the message publishing, any MQTT subscription can be analyzed as well before being actually forwarded to the target MQTT broker by overriding the canSubscribe method:

In this case, the subscription parameter comes in handy to assist you in deciding whether to proceed with the request. See the MqttSubscription API reference for a complete description.

As a complementary example of the one proposed for the publishing case, the following implementation disallows any subscription that requires QoS 2, or that specifies a topic filter starting with "$":

On the client side, the unauthorized subscription request will be signaled through the onNotAuthorized callback function as introduced in Section 3.10.2, “Subscribe Options”:

As always, the responseObject parameter follows the same common pattern for all Authorization Requests as illustrated in the previous sections.

In the diagram below, the sequence related to a subscription request that goes through the Hook before being conveyed to the MQTT broker.

Let’s finish this chapter on the Hook development with a quick overview of the so-called Simple Notifications methods, which are invoked when long-term activities like sessions, connections, and subscriptions complete their own life cycle.

For example, a session opened against MQTT.Cool could end due to either an explicit request made by the client or any network issue; in such a case, the onSessionClose method is invoked; therefore, you could override it to apply your own cleanup logic, if any:

Similarly, a connection established with any MQTT broker may be explicitly closed by the originating client (see Section 3.13, “Disconnecting”): you will be informed of this event through onDisconnection:

Lastly, a currently active subscription may be terminated by an unsubscription request (see Section 3.11, “Unsubscribing”), which will be reported by the onUnsubscribe method:

The provided LightstreamerClient instance is already configured and initialized to be used by the MQTT.Cool library for establishing the connection toward the target MQTT.Cool server.

However, you have the opportunity to manage the attached ConnectionOptions instance to set specific connection properties as per your needs.

For example, you might want to change default values for properties related to possible timeouts, like the following:

and so on.

Similarly, through setForcedTransport method you could force a fixed transport (for example, HTTP only), disabling the native Stream-Sense algorithm.

See the ConnectionOptions API reference for the complete list of modifiable properties.

As already stated, onLsClient is the expected place where to apply any change to the connection just before it is actually established. We are now ready to complete the main connection pattern extension started here: