Getting started with the MQTT client for Java

Get up and running with the MQTT client for Java sample applications, using either IBM® MessageSight or IBM WebSphere® MQ as the MQTT server. The sample applications use a client library from the MQTT software development toolkit (SDK) from IBM. The SampleAsyncCallBack sample application is a model for writing MQTT applications for Android and other event-driven operating systems.

Before you begin

About this task

The purpose of the task is to check that you can build and run an MQTT client for Java sample application, connect it to IBM WebSphere MQ or IBM MessageSight as the MQTT version 3 server, and exchange messages.

Follow this task to run the sample application from the Eclipse workbench, or from a command line. The steps in the example are for Windows. With small modifications, you can run the sample application on any platform that supports JSE 1.5 or above.

You can run applications on the same server as IBM WebSphere MQ, where the environment for running applications that connect to IBM WebSphere MQ is configured for you. Follow the task Configuring the MQTT service from the command line to install and configure IBM WebSphere MQ with the IBM WebSphere MQ Telemetry option on Windows or Linux®. When the environment is installed and configured, run the sample application, MQTTV3Sample, to verify the installation.

Procedure

  1. Choose an MQTT server to which you can connect the client app.

    The server must support the MQTT version 3.1 protocol. All MQTT servers from IBM do this, including IBM WebSphere MQ and IBM MessageSight. See Getting started with MQTT servers.

  2. Optional: Configure the MQTT server.
  3. Download the Mobile Messaging and M2M Client Pack and install the MQTT SDK.
    There is no installation program, you just expand the downloaded file.
    1. Download the Mobile Messaging and M2M Client Pack.
    2. Create a folder where you are going to install the SDK.

      You might want to name the folder MQTT. The path to this folder is referred to here as sdkroot.

    3. Expand the compressed Mobile Messaging and M2M Client Pack file contents into sdkroot. The expansion creates a directory tree that starts at sdkroot\SDK.
  4. Install a Java development kit (JDK) Version 6 or later.

    Because you are developing a Java app for Android, the JDK must come from Oracle. You can get the JDK from Java SE Downloads.

  5. Compile and run one or more of the MQTT client for Java sample applications:

    The following MQTT client sample Java apps are included in the SDK:

    MQTTV3Sample
    The sample is also included with IBM WebSphere MQ and links to the com.ibm.micro.client.mqttv3.jar package.
    Sample
    Sample is in the Paho package and links to the org.eclipse.paho.client.mqttv3 package. It is similar to MQTTV3Sample; it waits until each MQTT action is completed.
    SampleAsyncWait
    SampleAsyncWait is in the org.eclipse.paho.client.mqttv3 package. It uses the asynchronous MQTT API; it waits on a different thread until an action completes. The main thread can do other work until it synchronizes on the thread that is waiting for the MQTT action to complete.
    SampleAsyncCallBack
    SampleAsyncCallBack is in the org.eclipse.paho.client.mqttv3 package. It calls the asynchronous MQTT API. The asynchronous API does not wait for MQTT to complete processing a call; it returns to the application. The application carries on with other tasks, then waits for the next event to arrive for it to process. MQTT posts an event notification back to the application when it completes processing. The event driven MQTT interface is suited to the service and activity programming model of Android and other event driven operating systems.
    As an example, look at how the mqttExerciser sample integrates MQTT into Android using the service and activity programming model.
    mqttExerciser
    mqttExerciser is a sample program for Android. Because it is built and run differently, it is described separately. See Getting started with the MQTT client for Java on Android.

Results

You compiled and ran the MQTT Java sample applications that are connected to IBM WebSphere MQ or IBM MessageSight as the MQTT server.

What to do next

Study the Javadoc reference information; see step 3 of Compile and run all the MQTT client sample Java apps from Eclipse. Alternatively open the Javadoc html files that are in the SDK\clients\java\doc\javadoc directory in the Mobile Messaging and M2M Client Pack.

Compile and run the Paho sample programs from the command line

Compile and run the Paho sample application Sample.java from the command line. The sample is in the MQTT SDK. The sample is built with the MQTT Paho client libraries in the org.eclipse.paho.client.mqttv3 package. It demonstrates an MQTT publisher and subscriber. Two other Paho samples in the same directory can be built and run the same way. They differ by calling the MQTT library asynchronously.

Before you begin

Do steps 1 to 4 in the main task to configure an MQTT server and download the Mobile Messaging and M2M Client Pack.

About this task

Compile and run Sample.java from the SDK client samples subdirectory SDK\clients\java\samples. The Java code is in the directory, SDK\clients\java\samples\org\eclipse\paho\sample\mqttv3app.

Procedure

  1. Create a script in the client samples directory to compile and run Sample on your chosen platform.

    The following script compiles and runs the sample on Windows.

    Figure 1. Compile and run Sample.java
    @echo on
setlocal
set classpath=
set JAVADIR=C:\Program Files\IBM\Java70\bin
"%JAVADIR%\javac" -cp ..\org.eclipse.paho.client.mqttv3.jar .\org\eclipse\paho\sample\mqttv3app\Sample.java
start "Sample Subscriber" "%JAVADIR%\java" -cp  .;..\org.eclipse.paho.client.mqttv3.jar org.eclipse.paho.sample.mqttv3app.Sample -a subscribe -b localhost -p 1883
@rem Sleep for 2 seconds
ping -n 2 127.0.0.1 > NUL 2>&1
"%JAVADIR%\java" -cp  .;..\org.eclipse.paho.client.mqttv3.jar org.eclipse.paho.sample.mqttv3app.Sample -b localhost -p 1883
pause
endlocal
  2. Run the script.
    Results:
    Figure 2. MQTTV3Sample Subscriber
    Connected to tcp://localhost:1883 with client ID SampleJavaV3_subscribe
Subscribing to topic "Sample/#" qos 2
Press <Enter> to exit
Time:   2012-11-09 17:23:22.718  Topic: Sample/Java/v3  Message:        Message
from blocking MQTTv3 Java client sample  QoS:   2
    Figure 3. MQTTV3Sample Publisher
    Connecting to tcp://localhost:1883 with client ID SampleJavaV3_publish
Connected
Publishing at: 2012-11-09 17:22:07.734 to topic "Sample/Java/v3" qos 2
Disconnected

    If you leave the subscriber application running, you cannot run the same subscriber again. The client identifier of the new subscriber is the same as the old subscriber. You cannot run two MQTT clients with the same client identifier at the same time. You can set the -i option to set the client identifier so you can run different subscribers at the same time.

    If you run the same client again, you can take advantage of the -c option to start and start the client with cleansession set to false. With that option you can explore the behavior of interrupted client sessions.

  3. End the subscriber by pressing enter or closing the window.

What to do next

Create scripts to compile and run the other samples in the SDK\clients\java\samples\org\eclipse\paho\sample\mqttv3app subdirectory. Copy the script in Figure 1 and replace Sample with SampleAsyncWait or SampleAsyncCallBack. The other samples are asynchronous versions of the synchronous Sample program.

SampleAsyncWait
SampleAsyncWait is in the org.eclipse.paho.client.mqttv3 package. It uses the asynchronous MQTT API; it waits on a different thread until an action completes. The main thread can do other work until it synchronizes on the thread that is waiting for the MQTT action to complete.
SampleAsyncCallBack
SampleAsyncCallBack is in the org.eclipse.paho.client.mqttv3 package. It calls the asynchronous MQTT API. The asynchronous API does not wait for MQTT to complete processing a call; it returns to the application. The application carries on with other tasks, then waits for the next event to arrive for it to process. MQTT posts an event notification back to the application when it completes processing. The event driven MQTT interface is suited to the service and activity programming model of Android and other event driven operating systems.
As an example, look at how the mqttExerciser sample integrates MQTT into Android using the service and activity programming model.

The asynchronous samples demonstrate how to reduce the amount of time that an MQTT application blocks while it is waiting for the MQTT client. It is important to eliminate blocking calls in the main thread to increase responsivity and battery life in a mobile environment.

The samples demonstrate two patterns for calling asynchronous interfaces in the MQTT client.
  1. SampleAsyncWait does not block while the MQTT is waiting for network interactions.
  2. SampleAsyncCallBack does not block waiting for the MQTT client to complete any actions. The latter is necessary when a JavaScript page is calling the MQTT client from a browser. JavaScript pages must not block. Responses to actions must be posted back to the main browser thread, which calls the MQTT event handler you write to process the notification.

Compile and run all the MQTT client sample Java apps from Eclipse

Compile and run the MQTT client sample Java apps that are in the Mobile Messaging and M2M Client Pack. They demonstrate a MQTT publisher and subscriber.

About this task

Compile and run the MQTT Java samples, Sample, and MQTTV3Sample in Eclipse. Sample is in the sdkroot\SDK\clients\java\samples\org\eclipse\paho\sample\mqttv3app SDK clients subdirectory and MQTTV3Sample.java is in sdkroot\SDK\clients\java\samples.

Procedure

  1. Download Eclipse IDE for Java Developers.
  2. Create a Java project that is called MQTT Samples in Eclipse.
    1. File > New > Java project and type MQTT Samples. Click Next.

      Check the JRE is at the correct or later version.JSE must be at version 1.5 or later.

    2. In the Java Settings window, click Link additional source folders.
    3. Browse to the directory where you installed the MQTT Java SDK folder to. Select the sdkroot\SDK\clients\java\samples folder and click OK > Next > Finish.
    4. In the Java Settings window, click Libraries > Add External Jars
    5. Browse to the directory where you installed the MQTT Java SDK folder to. Locate the sdkroot\SDK\clients\java folder and select the org.eclipse.paho.client.mqttv3.jar and com.ibm.micro.client.mqttv3.jar files; click Open > Finish.

      The MQTTV3Sample.java sample links to com.ibm.micro.client.mqttv3.jar, and the samples in the paho directory tree link to org.eclipse.paho.client.mqttv3.jar. The com.ibm.micro.client.mqttv3.jar is retained so that existing MQTT applications continue to build and run without change.

    The MQTT Samples project builds with some warnings, but no errors.
    Figure 4. MQTT client for Java project
    Screen capture of Eclipse Package Explorer
  3. Optional: Install the MQTT client Javadoc.

    With the MQTT client Javadoc installed, the Java editor describes the MQTT classes in hover help.

    1. Open Package Explorer > Referenced Libraries in your Java project. Right click org.eclipse.paho.client.mqttv3.jar > Properties.
    2. In the Properties navigator click Javadoc Location.
    3. Click Javadoc URL > Browse in the Javadoc Location page, and find the SDK\clients\java\doc\javadoc folder > OK.
    4. Click Validate > OK

      You are prompted to open a browser to view the documentation.

    5. Repeat this procedure for the com.ibm.micro.client.mqttv3.jar file.
  4. Create a publisher and subscriber runtime configuration to run the mqttv3app.Sample application.
    1. Right-click the Sample class, click Run as > Run configurations.
    2. Right-click Java Application > New and type the name SampleSubscriber.
    3. Click the arguments tab, and type the program arguments followed by Apply. 
      -a subscribe -b localhost -p 1883
    4. Repeat the last step to create a SamplePublisher configuration by omitting the -a subscribe parameter.
  5. Run the mqttv3app.Sample subscriber followed by the publisher.
    1. Click Run > Run configurations
    2. Click SampleSubscriber > Run.
      Open the Console view. The subscriber is waiting for a publication.
      Connected to tcp://localhost:1883 with client ID SampleJavaV3_subscribe
Subscribing to topic "Sample/#" qos 2 
Press <Enter> to exit
    3. Click SamplePublisher > Run.
      Open the Console view. You see the publication that is created by the publisher:
      Connecting to tcp://localhost:1883 with client ID SampleJavaV3_publish
Connected
Publishing at: 2012-11-09 14:09:29.859 to topic "Sample/Java/v3" qos 2
Disconnected
    4. Switch console views to the subscriber console.

      The switch consoles icon is Screen capture of Eclipse Show consoles button.

      The subscriber received the publication:
      ...
Time: 2012-11-09 14:09:30.593  Topic: Sample/Java/v3  Message: Message from blocking MQTTv3 Java client sample  QoS: 2
  6. Optional: Create a publisher and subscriber runtime configuration for MQTTV3Sample.
    1. Right-click the MQTTV3Sample class, click Run as > Run configurations.
    2. Right-click Java Application > New and type the name MQTTV3SampleSubscriber.
    3. Click the arguments tab, and type the program arguments followed by Apply. 
      -a subscribe -b localhost -p 1883
    4. Repeat the last step to create an MQTTV3SamplePublisher configuration by omitting the -a subscribe parameter.
  7. Optional: Run the MQTTV3Sample subscriber followed by the publisher.
    1. Click Run > Run configurations
    2. Click MQTTV3SampleSubscriber > Run.
      Open the Console view. The subscriber is waiting for a publication.
      Connected to tcp://localhost:1883
Subscribing to topic "MQTTV3Sample/#" qos 2
Press <Enter> to exit
    3. Click MQTTV3SamplePublisher > Run.
      Open the Console view. You can see the publication that is created by the publisher.
      Connected to tcp://localhost:1883
Publishing to topic "MQTTV3Sample/Java/v3" qos 2
Disconnected
    4. Switch console views to the subscriber console.

      The switch consoles icon is Screen capture of Eclipse Show consoles button.

      The subscriber received the publication:
      MQTTV3Sample/Java/v3
Message: Message from MQTTv3 Java client
QoS:  2