Eclipse Paho Java - MQTT Client Library Encyclopedia
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 Public License
|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.
|Offline Message Buffering
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:
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 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
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:
We need to create a
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:
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
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:
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
Publish a retained Message
Publishing a retained message is very simple. You only need to set the
retained parameter of the
publish method to
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.
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).
Using TLS / SSL
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.
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.