Quick start guide for the Paho MQTT Java client

Posted on Jul 03, 2012

I was looking for interesting projects on The Eclipse Foundation website and found a project Paho. It relates to relatively new areas as Internet of Things, MQTT, IBM's Smart Planet idea, Machine-2-Machine communication, etc.

Now Paho is in the Incubation Phase but nevertheless it has working code which was contributed by the IBM. I found the short post by Andy Piper (one of Paho contributors) about how to build C client library and then build and run sample program.

Paho includes not only C client library but also Java. I decided to give it a try and desribed here all the steps from building it to testing it with sample Java application. Finally I was a bit upset that everything went smoothly without any black magic :)

Install Mosquitto

To test client library you can use MQTT broker from eclipse server (it is m2m.eclipse.org, by default sample application uses it), or install an open source MQTT broker like mosquitto on your host and use it.

There are two ways to install it:

  1. You can refer to Andy's post and use apt-get
  2. Download sources and build mosquitto manually

I tried to build it manually and had a success. The steps are pretty simple:

lynx@wonderland$ wget http://mosquitto.org/files/source/mosquitto-0.15.tar.gz
lynx@wonderland$ tar -zxf mosquitto-0.15.tar.gz 
lynx@wonderland$ cd mosquitto-0.15
lynx@wonderland$ make
lynx@wonderland$ cd src
lynx@wonderland$ ./mosquitto

Build Java client library

Download the latest sources from Paho repository:

lynx@wonderland$ git clone http://git.eclipse.org/gitroot/paho/org.eclipse.paho.mqtt.java.git

After you will get directory org.eclipse.paho.mqtt.java with two subdirectories:

org.eclipse.paho.client.mqttv3 - client library
org.eclipse.paho.sample.mqttv3app - sample application

To build client library you can use ant:

lynx@wonderland$ cd org.eclipse.paho.client.mqttv3
lynx@wonderland$ ant

When the build finishes the library will be written to /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar

To generate javadoc:

javadoc -sourcepath src -subpackages "org.eclipse.paho.client.mqttv3" -d doc

Build sample application

To build the sample application you need to have the client library and specify it to Java compiler.

$ cd org.eclipse.paho.sample.mqttv3app
$ mkdir bin
$ javac -d bin -classpath /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar \
> src/org/eclipse/paho/sample/mqttv3app/Sample.java

Run sample application

Sample application supports many options and can not only publish but also subscribe to some topics. To get help:

$ java -classpath /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar:bin \
> org.eclipse.paho.sample.mqttv3app.Sample -h

Lets make it publish a message to our mosquitto:

$ java -classpath /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar:bin \
> org.eclipse.paho.sample.mqttv3app.Sample -b localhost
Connected to tcp://localhost:1883
Publishing at: 1343693983820 to topic "Sample/Java/v3" qos 2

If you did everything correct on mosquitto stdout you will get something like:

1343693983: New connection from
1343693983: New client connected from as SampleJavaV3_publish.

You can also check the subscription to some topics (by default sample application uses topic Sample).

$ java -classpath /tmp/Mqttv3ClientOut/ship/org.eclipse.paho.client.mqttv3.jar:bin \
> org.eclipse.paho.sample.mqttv3app.Sample -b localhost -a subscribe
Time:	1343694288210  Topic:	Sample/Java/v3  Message:	Message from MQTTv3 Java client  QoS:	2