Skip to content

Eclipse Paho Java - MQTT Client Library Encyclopedia

by Dominik Obermaier
12 min read

Eclipse Paho is an umbrella project for several MQTT and MQTT-SN client implementations in different programming languages. The Eclipse Paho project was one of the first open source MQTT client implementations available and is actively maintained by a huge community. Paho also features a Java client, which is suited for embedded use, Android applications and Java applications in general. The initial code base was donated to Eclipse by IBM in 2012.

Why Use Eclipse Paho Java MQTT Client?

Eclipse Paho
Language Java
License Eclipse Public License
API Style Synchronous and Asynchronous

The Java version of Eclipse Paho is rock-solid and is used by a broad range of companies from different industries around the world to connect to MQTT brokers. The synchronous/blocking API of Paho makes it easy to implement the applications MQTT logic in a clean and concise way while the asynchronous API gives the application developer full control for high-performance MQTT clients that need to handle high throughput. The Paho API is highly callback based and allows to hook in custom business logic to different events, e.g. when a message is received or when the connection to the broker was lost. Paho supports all MQTT features and a secure communication with the MQTT Broker is possible via TLS.

Features Supported By Eclipse Paho Java MQTT Client Library

MQTT 3.1 Yes
MQTT 3.1.1 Yes
Automatic Reconnect Yes
Disk Persistence Yes

Advanced Features Supported By Eclipse Paho Java MQTT Client Library

QoS 0 Yes
QoS 1 Yes
QoS 2 Yes
Authentication Yes
Throttling No
Offline Message Buffering Yes

Usage of Features Supported By Eclipse Paho Java MQTT Client Library

How to Install Eclipse Paho Java MQTT Client Library?

The Java Paho library is available as .jar file from the project page and can be used without any further dependencies by including it to your Java classpath.

The most convenient way to install Paho is to use a dependency management tool like Maven, Gradle or Ivy. The following examples use Maven but it should be trivial to port that to Gradle or Ivy. Paho isn’t available in Maven Central, so the following repository has to be added to your pom.xml:

        <id>Eclipse Paho Repo</id>

Now you can add the following to your dependencies section in order to download Paho:


Creating a Client Object

All MQTT operations are exposed via a MqttClient object. Before connecting, publishing or subscribing, the user needs to create an instance of this MqttClient first.

MqttClient client = new MqttClient( 
    "tcp://", //URI 
    MqttClient.generateClientId(), //ClientId 
    new MemoryPersistence()); //Persistence

A MqttClient always needs an URL and a client identifier in order to be able to connect to a MQTT broker. Please note that Paho expects the connection String to be a valid URI and you need to specify the protocol first (in our case TCP). It’s also required to specify the port you want to connect to. The MQTT client identifier needs to be unique (if you’re not familiar with the client identifier concept of MQTT, read this blog post about MQTT connection establishment), in the example we’re using a utility method from Paho to generate a client identifier for temporary usage. Since we don’t want to persist the state of pending QoS messages and the persistent session we are just using a in-memory persistence. If you omit this parameter, a file-based persistence is used by default.

Please note, that after the creation of the MqttClient you need to connect to the broker first before you are able to do any MQTT operation.


After obtaining a MqttClient object, connecting to a MQTT broker is very easy:


The client is now connected. You can check if the client is already connected by using the below code.


Connect with MQTT 3.1 or MQTT 3.1.1

Depending which MQTT broker you are using, you may want to explicitely connect with a specific MQTT version. If you’re not sure which version to use, read this blog post about MQTT version differences.

By default, Paho tries to connect with MQTT 3.1.1 and falls back to MQTT 3.1 if it’s not possible to connect with 3.1.1.

Connecting with a specific version is easy:

MqttConnectOptions options = new MqttConnectOptions();

// options.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1);


We need to create an MqttConnectOptions object first and set the specific version. When connecting, we need to pass this MqttConnectOptions object to the client in order to use it.

Connect with LWT

In order to use MQTTs Last-Will-and-Testament feature, we can also use a MqttConnectOptions object as we have seen above:

MqttConnectOptions options = new MqttConnectOptions();

    "topic", // topic 
    "payload".getBytes(UTF_8), // payload 
    2, // QoS 
    false); // retained?

We need to specify all relevant LWT data like the topic, the payload of the message, the Quality of Service level and if this message should be a retained message.

Connect with Username/Password

Paho also supports authentication via username / password

MqttConnectOptions options = new MqttConnectOptions();

While the username needs to be a string, the password is passed to the MqttConnectOptions object as char array.


After connecting to a MQTT broker, a typical action is to publish a MQTT message. With Paho this is pretty straightforward with this one-liner:

    "topic", // topic 
    "payload".getBytes(UTF_8), // payload 
    2, // QoS 
    false); // retained?

We can control all relevant MQTT information like the topic, the payload, the Quality of service and if the message should be retained. Paho expects you to connect to the MQTT broker first, otherwise you’ll receive a MqttException.

Publish a Retained Message

Publishing a retained message is very simple. You only need to set the retained parameter of the publish method to true:

    "topic", // topic 
    "payload".getBytes(UTF_8), // payload 
    2, // QoS 
    false); // retained?


In order to receive messages a client must subscribe to one or more MQTT topics with the desired QoS level. If you want to react on incoming MQTT messages, you need to set a callback first. This callback is called on specific events, e.g. when a message arrives.

client.setCallback(new MqttCallback() {

    public void connectionLost(Throwable cause) { //Called when the client lost the connection to the broker 

    public void messageArrived(String topic, MqttMessage message) throws Exception {
        System.out.println(topic + ": " + Arrays.toString(message.getPayload()));

    public void deliveryComplete(IMqttDeliveryToken token) {//Called when a outgoing publish is complete 
client.subscribe("#", 1);

It’s important to note that the callback needs to be set before the client connects to the MQTT broker, otherwise you could lose messages, especially after resuming a persistent session.

To subscribe to messages, you can use the method subscribe, which takes a topic and a QoS level as parameter. There is also an overloaded subscribe method available if you want to subscribe to more than one MQTT topic at once.


Unsubscribing from specific topics is straightforward:


There is also an overloaded unsubscribe method available which lets you unsubscribe from several MQTT topics at once.


Sometimes MQTT clients need to disconnect gracefully. This is also straightforward with Paho:


The disconnect method will wait until all pending operations (like pending QoS 2 messages) are finished before sending the MQTT DISCONNECT message. There is an overloaded method which allows you to set the timeout manually if you don’t like the default timeout (30 seconds).


Paho supports SSL by using the standard Java SocketFactory approach. The code below is not complete but you will get the idea how SSL / TLS is set up with Paho.

MqttClient client = new MqttClient("ssl://yourbroker:8883", MqttClient.generateClientId(), new MemoryPersistence());

SSLContext sslContext = SSLContext.getInstance("SSL");
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
KeyStore keyStore = readKeyStore();
sslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());

MqttConnectOptions options = new MqttConnectOptions();


You first need to specify “SSL” as protocol for the connection string (also note the port 8883 which is standard for secure MQTT), so Paho is aware of the fact that you want to connect with a secure communication channel. You then need to provide a SSLSocketFactory and pass it to the MqttOptions object. If specifying a TrustManagerFactory, you can connect to trusted MQTT brokers, even with self-signed certificates.

Since Paho uses standard Java SSL mechanisms, you can also use e.g. BouncyCastles or other security libraries which may provide better APIs than the default JDK APIs.

Fast-track IoT and IIoT application development cycles with reliable MQTT clients. Explore why use MQTT Client Libraries?

Dominik Obermaier

Dominik Obermaier is CTO and co-founder of HiveMQ. He is a member of the OASIS Technical Committee and is part of the standardization committee for MQTT 3.1.1 and MQTT 5. He is the co-author of the book “The Technical Foundations of IoT” and a frequent speaker on IoT, MQTT, and messaging.

  • Dominik Obermaier on LinkedIn
  • Dominik Obermaier on X
  • Contact Dominik Obermaier via e-mail
HiveMQ logo
Review HiveMQ on G2