Integrate your applications using IBM Bluemix MQ Light Service

21 July 2014
PDF (314 KB)
Mark Phillips

Mark Phillips

MQ Cloud Technical Lead


Melanie Rao

Melanie Rao

MQ Cloud Software Engineer

IBM® MQ Light™ is a beta-level product, and it will be changing as we continually make things better and easier to use.

Sign up for IBM Bluemix
This cloud platform is stocked with free services, runtimes, and infrastructure to help you quickly build and deploy your next mobile or web application.

MQ Light provides a flexible and easy-to-use messaging service for applications deployed on IBM Bluemix. You can use MQ Light as a queuing service to send single messages to individual recipients by way of queues, or as a publish/subscribe broker for sending notifications to multiple recipients. For example, the service can be used by a mobile or web application that needs to process a number of videos, a rather CPU intensive task. This can be offloaded to multiple instances of a back-end worker application on the cloud. Each of these workers can then reply to a response queue asynchronously, allowing the mobile or web application to collect their responses.

Two APIs are supported: the MQ Light Java™ Message Service (JMS) API and the MQ Light API.

  • The MQ Light JMS API is the standard Java Messaging API, used by Java Enterprise Edition (Java EE) applications to perform messaging based on the point-to-point or publish/subscribe models. This API is used in the sample presented in this article.
  • The MQ Light API provides support for Node.js applications. It is designed to be simple to use, providing the basic messaging capabilities that applications need to be scalable and responsive. For more information, see IBM Messaging: MQ Light concepts.

After you have configured MQ Light, for the majority of uses, the service does not require ongoing administration.

For issues that you may encounter with this service, go to the Get help page on the Bluemix Developers Community site.

What you'll need to build your app

  • Familiarity with Java and a Java development environment
  • A basic understanding of messaging concepts
  • A Bluemix account
  • CloudFoundry's cf command line tool (follow the Bluemix command line interface instructions to install and learn how to use it)
  • Apache ANT
  • Git
  • An IBM DevOps Services project containing the source code for both parts of the sample (click on the Get the code button above)

Step 1. Getting started with the MQ Light JMS API


To help you familiarize yourself with the MQ Light JMS API, here is a quick walk-through describing how to deploy a sample application, which binds to an MQ Light instance on Bluemix, takes a sentence that you enter, and then converts the words in the sentence to uppercase.

Diagram of how MQ Light breaks sentence into uppercase words and sends responses

The sample has two parts:

  • A web application that is implemented as a Java servlet, packaged as a Java EE .war file. The application accepts text input on a web page, breaks the text into words, sends the words to the worker application, and receives the processed words as reply messages. These messages are then dynamically displayed on the web page along with the worker identifier string. The servlet web application demonstrates how to deploy a JEE application into Liberty, how to use a JNDI look-up to establish a connection to MQ Light, and how to send and receive messages to and from queues.
  • A Java SE worker application that is deployed to Bluemix, which takes words that are entered by you, converts them to uppercase, and then puts the information on a queue. The Java JMS worker program demonstrates how to bind a JMS application to an MQ Light service instance by using the MQ Light helper class, how to use the MQ Light protocol to get request messages from one queue and put reply messages on another queue, and how multiple worker applications can be used to process messages on a queue.

Step 2. Downloading and compiling the source code


The source code for this sample is stored in an IBM DevOps Services project. You will need to clone a Git repository and a Java SDK to download and build the sample. You can get the code from the IBM DevOps Services project by clicking on the Get the code button near the beginning of this article.

To get the source code and build the parts of the sample:

  1. Use the Git URL specified on the IBM DevOps Services project to clone the Git repository (see the DevOps Services Help section for additional help).
  2. Run ant from the top level directory to build the binaries for the web application, which will be placed under mqlightsampleweb, and for the worker application, which will be placed under mqlightsampleworker. If you modify the source code, do no forget to rerun ant to generate the updated binaries.

Step 3. Working with the JMS worker application


The following code shows a simplified version of the program with error checking and declarations removed:

MQLightConnectionHelper connHelper = 
Connection conn = connHelper.getJmsConnectionFactory()
			.createConnection(connHelper.getUsername(), connHelper.getPassword());
Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
Queue queue = sess.createQueue("jms/requestQueue");
MessageConsumer consumer = sess.createConsumer(queue);
while (errorCount < 10) {
     Message message = consumer.receive();
     Destination replyDestination = message.getJMSReplyTo();
     MessageProducer replyProducer = sess.createProducer(replyDestination);
     TextMessage replyMessage = sess.createTextMessage();
     msg = ((TextMessage) message).getText().toUpperCase();
     replyMessage.setText(msg + "\tProcessed by worker ID: " + ID);

Except for the first line, this code is a typical JMS consumer program, which consumes a message from the request queue, performs some work (converting the message to uppercase), and puts the processed message to the reply queue.

The first line uses the provided MQLightConnectionHelper class to simplify the process of getting a JMSConnectionFactory. When the MQLightConnectionHelper class is instantiated, it parses the VCAP_SERVICES environment variable, which contains the information needed to connect to the first MQ Light instance bound to the application. A static getter with no arguments returns the singleton helper with the following methods to get a connection factory and connection information:

getJMSConnectionFactory() // Get a JMSConnectionfactory to the default connection
getUsername() // The user credential for the bound service as a string
getPassword() // The password credential for the bound service as a string
getConnectionLookupURI() // The URI of the client connection definition table used to connect to the qmgr

Step 4. Working with the JMS web application


The Java servlet sends a request message to the back-end service in response to an HTTP POST that is sent from the HTML client web page. The following code snippets show a simplified version of the program with error checking and declarations removed.

The servlet is packaged as a Web Application Archive (WAR) file, which contains the web content to be served by the container the application is deployed into, along with a descriptor about the deployment (web.xml). A ConnectionFactory is required to put and get messages onto queues through the MQ Light service. It is described as a resource reference in the deployment descriptor.

	<description> ConnectionFactory used to send and receive messages to and 
      from the back-end worker.

The servlet is initialized and an InitialContext to the container JNDI space is obtained, allowing the look-up of the connection factory from the local JNDI space (NB: the lookup relies on the bound service instance being named mqlsampleservice). The local resources which are needed are here created programmatically using the JMS API.

InitialContext ctx = new InitialContext();
ConnectionFactory myCf = (ConnectionFactory)ctx.lookup("java:comp/env/jms/mqlsampleservice");
Queue myRequestQueue =  session.createQueue("jms/requestQueue");
Queue myReplyQueue =  session.createQueue("jms/replyQueue");

When user input is submitted via the web page as a HTTP request, two steps are performed. In the first step, a request message is sent to the back-end worker application for each of the words of the input text on the sample web page.

	String message = (String) request.getParameter("message");
	Connection connection = myCf.createConnection(username, password);
	Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
	MessageProducer producer = session.createProducer(myRequestQueue);
	for (String word : messages) {
		TextMessage requestMsg = session.createTextMessage(word);

In the second step, the reply queue is checked for a response from the back-end worker processes. When a response from the worker threads is available, an HTML response is built with its contents and is returned as the HTTP response to the original query, allowing the web page to display the results of the worker processing.

	Connection connection = myCf.createConnection(username, password);
	Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
	MessageConsumer consumer = session.createConsumer(myReplyQueue);
	while ((replyMsg = (TextMessage) consumer.receive(1000)) != null) {


	generateReply(response, "SUCCESS!", replyMsgTxt);

Step 5. Deploying and running on Bluemix

  1. If you have not done so already, build the JMS web and worker applications by running ant in the top level directory. This produces a JAR file named MQLightSampleWorker.jar in mqlightsampleworker, and a WAR file named MQLightSampleWeb.war in mqlightsampleweb.
  2. Log in to Bluemix using the CloudFoundry command line interface (see Logging in to Bluemix for more details).
    cf login
  3. Create an instance of the MQ Light service, which will be shared by both the web and the worker applications of the sample, using the CloudFoundry command line interface. The service instance has to be named mqlsampleservice, as explained in Step 4 of this article.
    cf create-service mqlight Default mqlsampleservice

    To list the service you created, enter the following command:

    cf services
  4. Push both applications and bind them to the service instance you created by running the following command from the mqlight directory:
    cf push

    This command uses the configuration specified in manifest.yml to perform the following steps automatically:
    1. Create an application named MQL.sample.worker, and upload MQLightSampleWorker.jar.
    2. Bind MQL.sample.worker to your MQ Light service instance.
    3. Start two instances of the MQL.sample.worker application, each having 512 MB of available memory.
    4. Create an application named MQL.sample.web, and upload MQLightSampleWeb.war.
    5. Create and bind a unique route to MQL.sample.web, providing a URL to access the application externally. This URL is unique by using the ${random-word} keyword in the host attribute, which generates a random string.
    6. Bind the MQL.sample.web application to your MQ Light service instance.
    7. Start one instance of the MQL.sample.web application, with 512 MB of available memory.
  5. You can display the web application by copying its URL (stated at the end of the results of the cf push command next to the "urls" character string), and pasting it into your browser. As shown in the image below, you can type a sentence into the web page's input box, and click Submit Work to see the worker offload in action. The sentence is sent via MQ Light to the worker threads for processing, and the results are displayed alongside the ID of the worker thread that processed each word! Diagram of the sample app's web UI showing an input box



And that's it! Several instances of the worker application can now communicate with the web front-end, using the MQ Light messaging service and its JMS API, all hosted on the cloud and available anywhere.

RELATED TOPICS:BlueMix Developers CommunityUsing WebSphere MQ classes for JMSMQ Light beta

Add a comment

Note: HTML elements are not supported within comments.

1000 characters left

developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Zone=WebSphere, Cloud computing
ArticleTitle=Integrate your applications using IBM Bluemix MQ Light Service