What you will learn

  1. How to start an IBM MQ Developer Environment for microclimate
  2. Import a microclimate application
  3. Running an application

What you will need

  1. Installed microclimate
  2. MicroclimateMQSample.zip sample

Install microclimate

Microclimate can be installed locally on your individual machine (Linux, Mac and Windows operating systems are supported), or within an IBM Cloud Private installation. This tutorial assumes a local installation. If you already have microclimate installed, continue to the next section. To install microclimate, go to the microclimate Getting Started page. Once you’ve installed microclimate, come back to continue with the tutorial.

Starting the MQ Developer environment

Microclimate uses docker containers for the application runtimes, and therefore a MQ container will be used for MQs runtime. The MQ container will deliberately be configured for development activities, and the MQ data will be stored within the container, so it can be disposed of easily when environments are recycled. If you are interested in a more comprehensive docker container environment please see the docker tutorial for more details.

Pull the image from Docker hub that contains the latest version of the MQ server:

docker pull ibmcom/mq:latest

When it’s done, check which images you have:

docker images

You will see:

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
ibmcom/mq           latest              4c0dd6b16b70        2 days ago          773MB

Now that the MQ server image is in your local Docker repository, you can run the container to stand up MQ in Ubuntu.

We’ve added parameters to the docker run command, for example to accept the license for IBM MQ Advanced for developers and name the queue manager where our queue will live.
Because MQ is running inside the container and isolated from the rest of the world, we’ve opened a couple of ports that MQ uses. The queue manager listener listens on port 1414 for incoming connections and port 9443 is used by MQ console. The sample application will use the listener port and MQ Console dashboard can be seen in your browser on port 9443. The MQ container is associated with the microclimate docker network, so we can refer to the container using the hostname QM.

Run the MQ server container.

docker run -e LICENSE=accept -e MQ_QMGR_NAME=QM1 -e LOG_FORMAT=json -p 1414:1414 -p 9443:9443 --network microclimate_network --network-alias QM -detatch ibmcom/mq

You’re creating a queue manager which has been set up with some simple default configuration to help you connect your first client application.
Give the container a moment to start, then check it’s running:

docker ps

You will see:

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                     PORTS                                            NAMES
<your container id> ibmcom/mq:latest    "runmqdevserver"    33 seconds ago      Up 29 seconds    >1414/tcp,>9443/tcp   mq-image   

Congratulations! You’ve just created your first simple queue manager. It’s called QM1 and it’s running inside the container.

Importing sample microclimate application

Launch microclimate using the standard command:

~/mcdev start -o

This will launch your default browser and load microclimate. Let’s import our MQ sample application, click on Import project:

microclimate home

Download the sample application from here.

Select the Project archive option and select Select archive file. Navigate to the MicroclimateMQSample.zip and click Open and Next:

The project name will be available for customization, click Import to continue:

This will automatically import the project and start the build. You can navigate to the build tab to see the progress:

Running and testing the microclimate application

The previous section imported the application and automatically started the build. Once the built is complete and the application has started the indicator at the top should change to green:

The sample application is a web based currency conversion application. The application will submit a HTTP request to the application server. A servlet will handle the request and send a message using MQ to the currency conversion application. A Message Driven Bean (running on the application server) will consume the MQ message and generate a response, that will be returned to the web page. To try the application click on the Open App link:

Append the following onto the URL: MQLibertyConversionApp and press enter:

Click Next, and type in a value within the exchange field and click Convert:

Scroll down and you should see quotes appear for the conversion:

Congratulations! You successfully imported and built your first Microclimate and MQ application, sent a series of messages to an IBM MQ queue and had these processed. You also set up your environment with everything you need to develop in microclimate with IBM MQ.

Explore the code

Click to explore the code

As mentioned in the previous sections there are two aspects to our sample application:

  1. ExchangeRateServlet: this servlet receives HTTP requests from the browser and converts into a MQ request for the currency conversion application.
  2. ProcessPayment: simulates the currency conversion application and is implemented as a message driven bean. This receives the MQ message, and generates a conversion rate that is returned to the Servlet using MQ.

To review the code, click on the Edit code tab, select Files and expand microclimatemqsample → src → main → java → com → demo → mqpure:
Double click on the ExchangeRateServlet.java to view the servlet. Scroll down to line 92 and you will see the doPost method that completes the majority of the processing. Here it receives the HTTP post request, converts into a JMS message and sends the message. The code will wait upto 2 minutes for a response, and if a message is received will be returned to the caller in response.

Double click on the ProcessPayment.java to view the message driven bean representing the currency conversion application. Scroll down to line 41 and you will see the onMessage method that processes incoming messages. This method queries the message for the location of the reply, creates a response to the request and replies back with the currency conversion.

There are a couple of interesting configuration files that you will want to review:

  1. src → main → liberty → config → server.xml: this is the configuration file for the liberty server, and includes the configuration for the IBM MQ resources. Lines 29 to 47 are the specific MQ aspects to highlight. These include the definition for the JMS connection factory, activation specification and queues.
  2. pom.xml: this is the maven file for the project. Within the file we added the IBM MQ Resource Adapter as a dependency (line 65), so it is included within the deployment. Later in the file (line 191) you will see that we copy the resource adapter to a particular location within the liberty server.