Verifying WebSphere Message Broker V6 without using the toolkit

Document options Document options requiring JavaScript are not displayed Sample code My developerWorks needs you! Connect to your technical community Rate this page Help us improve this content

Level: Intermediate

James Taylor (jamest@uk.ibm.com), Software Engineer, IBM

18 Jan 2006

This article describes how to verify a run-time only installation of WebSphere Event Broker or WebSphere Message Broker V6. The process described can be scripted to simplify the task of checking a working system, and using the concepts in this article, other system setup and deployment scenarios, beyond simple verification.

Introduction

This article shows you how to to set up and use a sample configuration to verify installations of IBM® WebSphere® Event Broker and IBM WebSphere Message Broker V6, hereafter referred to collectively as WebSphere Message Brokers.

The default configuration wizard and samples supplied with WebSphere Message Brokers rely on a full install of the run time and toolkit on the same machine. The documented way to verify a working system after installation uses these tools, which excludes most platforms and any machines where you choose not to install the toolkit. Relying on the GUI environment also limits the possibilities in terms of automation for install verification.

You can replicate everything done by the wizards without using the toolkit by completing the following tasks, which are described below. If you are already experienced in creating the run-time components, you can skip straight to the section Adding the broker to the domain, which has traditionally been done using the Broker Administration perspective.

1. Setting up a queue manager
2. Setting up a configuration manager
3. Setting up a broker database
4. Setting up a broker
5. Adding the broker to the domain
6. Preparing a sample broker application
7. Verifying the sample configuration

Assumptions

Some knowledge of WebSphere Message Broker will be helpful in using this article, though for those new to the product, brief descriptions and sample Linux® commands are given for each step. The IBM Redbook WebSphere Message Broker Basics is an excellent introduction to the product, and you can find detailed product documentation in the WebSphere Message Broker information center.

You should also be familiar with WebSphere MQ and your chosen database product. Specifically, in order to follow the manual verification steps, you must be able to create a queue manager and a database, along with an Open Database Connectivity (ODBC) connection for the database. If you download the accompanying zip file, you can use the verifyruntime.sh script to create a DB2 database on Linux, assuming DB2 has been installed and configured.

Creating a sample configuration

This section shows you how to set up a working system, including prerequisite components, a database, WebSphere MQ queue manager, a broker, and a configuration manager. Table 1 summarises suggested names and settings to use. If you are an experienced user, feel free to substitute your own values.

Table notes:

1. The port must not be in use by another application. If it is, pick the first available port after 1415.
2. To simplify the configuration, use the same user ID for all components (preferably the current logged-in user).
3. The user ID must be a member of the mqbrkrs group and must have administrator privileges on Windows®.

The following steps assume that WebSphere MQ V6.0, your chosen database product, and WebSphere Event Broker V6.0 or WebSphere Message Broker V6.0 are installed. For more detailed information on these steps, see Chapter 7 of the IBM Redbook WebSphere Message Broker Basics.

Before running any commands in WebSphere Message Brokers, set up the environment by running the product profile, so that multiple versions of the product can be installed and used on the same system. Listing 1 shows how to set up the correct environment for the default install location on Linux (be sure to include a space after the initial '.').

$ . /opt/ibm/mqsi/6.0/bin/mqsiprofile

MQSI 6.0.0.0
/opt/ibm/mqsi/6.0

$

Setting up a queue manager

The queue manager connects the broker and the configuration manager, and enables sample programs to communicate with the broker. For this simple configuration, a single queue manager is used by every component. A large distributed system usually has multiple connected queue managers.

For this step, create and start a WebSphere MQ queue manager and a TCP/IP listener. Use the suggested settings for the queue manager name and port number from Table 1, or record the values you use for reference below. The following commands show how to complete this step:

$ crtmqm MQSI60_SAMPLEQM
WebSphere MQ queue manager created.
Creating or replacing default objects for MQSI60_SAMPLEQM.
Default objects statistics : 40 created. 0 replaced. 0 failed.
Completing setup.
Setup completed.
$ strmqm MQSI60_SAMPLEQM
WebSphere MQ queue manager 'MQSI60_SAMPLEQM' starting.
5 log records accessed on queue manager 'MQSI60_SAMPLEQM' during the log replay phase.
Log replay for queue manager 'MQSI60_SAMPLEQM' complete.
Transaction manager state recovered for queue manager 'MQSI60_SAMPLEQM'.
WebSphere MQ queue manager 'MQSI60_SAMPLEQM' started.
$ runmqsc MQSI60_SAMPLEQM
5724-H72 (C) Copyright IBM Corp. 1994, 2005.  ALL RIGHTS RESERVED.
Starting MQSC for queue manager MQSI60_SAMPLEQM.

DEFINE LISTENER(MQSI60.LISTENER) TRPTYPE(TCP) PORT(1415) CONTROL(QMGR)
     1 : DEFINE LISTENER(MQSI60.LISTENER) TRPTYPE(TCP) PORT(1415) CONTROL(QMGR)
AMQ8626: WebSphere MQ listener created.
START LISTENER(MQSI60.LISTENER)
     2 : START LISTENER(MQSI60.LISTENER)
AMQ8021: Request to start WebSphere MQ Listener accepted.
END
     3 : END
2 MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.
$

Setting up a configuration manager

A configuration manager is used to manage a broker domain and is responsible for deploying message flow applications to the brokers in its domain. Create a configuration manager with the suggested name from Table 1, and specify the name of the queue manager created in the previous step. For simplicity, use the current logged-in user ID, making sure it is a member of the mqbrkrs group. If you use different settings, record the values for use in later steps.

Create and start the configuration manager, as shown in Listing 3, before moving on to the next step.

$ mqsicreateconfigmgr SAMPLE60_CM -i <user> -a <password> -q MQSI60_SAMPLEQM
Skipped Compiling {java/util/Hashtable}{rehash}
Skipped Compiling {java/util/Hashtable}{rehash}
AMQ8110: WebSphere MQ queue manager already exists.
WebSphere MQ queue manager running.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
BIP8071I: Successful command completion.
$ mqsistart SAMPLE60_CM
WebSphere MQ queue manager running.
BIP8096I: Successful command initiation, check the system log to ensure that the component started 
    without problem and that it continues to run without problem.
$

Setting up a broker database

Brokers use a database to store configuration data. Create a database using any of the supported database products. A suggested database name is shown in Table 1; otherwise record the name you use for use in later steps. You must also create an ODBC connection for the database to enable the broker to communicate with the database.

Database administration is outside the scope of this article. For more information, see the topic "Configuring the broker domain/Configuring broker domain components/Configuring databases" in the WebSphere Message Broker information center. It explains how to create a database using the provided DB2 product, including the required ODBC connection.

Setting up a broker

The broker hosts and runs message flow applications. Create a broker using the suggested settings in Table 1, or record the values you use for use in later steps.

Start the broker to complete the sample configuration, as shown in Listing 4 below. This is the configuration you will be verifying, but there is one more step before you can deploy a message flow application to exercise the sample configuration, which is covered in the next section.

$ mqsicreatebroker SAMPLE60_BK -i <user> -a <password> -q MQSI60_SAMPLEQM -n MQSI60SB
AMQ8110: WebSphere MQ queue manager already exists.
WebSphere MQ queue manager running.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
The setmqaut command completed successfully.
BIP8071I: Successful command completion.
$ mqsistart SAMPLE60_BK
WebSphere MQ queue manager running.
BIP8096I: Successful command initiation, check the system log to ensure that the component started 
    without problem and that it continues to run without problem.
$

Adding the broker to the domain

In order to deploy message flow applications to the broker you have created, it must be part of the domain administered by the configuration manager. In the past, this step has been done using the Broker Administration perspective in the toolkit, which is one of the reasons the installation verification and getting started samples can be run only on systems that have both the run time and toolkit installed. V6 offers an alternative way to add a broker to a domain using the Configuration Manager Proxy API, and this section describes how to use this tool.

Javadoc documentation for the configuration manager proxy API is provided with the broker run time, but the best way to get started, without writing any code, is to user the Configuration Manager Proxy Exerciser. This is a GUI application that can be used to invoke any part of the API, so in addition to providing a useful aid to learning about the API, you can use it to add the sample broker to the domain in order to continue the run-time verification.

Starting the Configuration Manager Proxy Exerciser

A Start menu item launches the Configuration Manager Proxy Exerciser on Windows, while on other platforms you must start it from the command line using the StartConfigManagerProxyExerciser script. Before using the script, the API JAR file must be on the classpath, which it will be if you have run mqsiprofile, along with ConfigManagerProxySamples.jar, as shown in Listing 5. If the system doesn't already have a JRE in the path, you can use the JRE inside the WebSphere Message Brokers install directory, also shown below:

$ export 
   PATH=$PATH:$MQSI_FILEPATH/jre/bin
$ export 
   CLASSPATH=$CLASSPATH:$MQSI_FILEPATH/sample/ConfigManagerProxy/ConfigManagerProxySamples.jar
$ $MQSI_FILEPATH/sample/ConfigManagerProxy/StartConfigManagerProxyExerciser

Connecting to configuration manager

The first thing you need to do once the GUI appears is to connect to a configuration manager. This could be on any system, since communication is handled via MQ by the API, and the process is exactly the same as using the local configuration manager, as described below.

Right-click on [Right-click to connect] in the top left-hand pane and select Connect to Configuration Manager. Enter values for Port and MQ Queue Manager from Table 1, leaving Host name as localhost, and ignore the security exit fields. After processing, you should see a table of methods and results in the top right pane, plus a message confirming that the exerciser is connected to the configuration manager at the bottom of the window.

Adding broker to topology

Once connected, you can use the exerciser to explore the API, or broker domain information, but all you need to do at this point is add the sample broker, created earlier, to the domain:

Right-click on PubSubTopology in the left pane and select Add broker to topology. Enter the New Broker name and New Broker's Queue Manager from Table 1. After processing, you should see the broker appear under PubSubTopology. Figure 1 shows what the Configuration Manager Proxy API Exerciser should look like at this point:

Preparing a sample broker application

Now that the sample configuration is set up and the broker has been added to the domain, everything is ready to deploy a message flow application to verify that the system is working. Any message flow application can be used; the Soccer Results sample is used in this article for the following reasons:

• It is easy to set up manually.
• The message flow is simple, and runs on WebSphere Event Broker and WebSphere Message Broker.
• It can be deployed on any system without modification.
• The applications used to drive the sample are command-line based and supplied with the run time.

The Soccer Results sample is covered in detail in the toolkit samples gallery, where it is described as "A sample that demonstrates simple publish/subscribe messaging, including the use of retained publications. The sample simulates the publication of soccer match scores while the soccer matches are being played."

The following steps describe how to set up the Soccer Results sample ready to verify the installation. Full instructions for preparing the sample manually, along with information on where to find the required resources, are provided in the toolkit sample gallery. To avoid the need for a toolkit install, the resources are provided in the accompanying zip file. Download the zip file and extract it to a convenient directory before you continue. I used /home/jamest.

Creating the sample queues

The Soccer Results sample uses WebSphere MQ to communicate with the message flow application running in the broker. Table 2 shows the queues and what they are used for:

The soccerqdefs.tst file, from the supplied zip file, can be used to set up the queues by entering the following command. If you used a different queue manager name, replace MQSI60_SAMPLEQM with the correct name:

$ runmqsc MQSI60_SAMPLEQM < soccerqdefs.tst
5724-H72 (C) Copyright IBM Corp. 1994, 2005.  ALL RIGHTS RESERVED.
Starting MQSC for queue manager MQSI60_SAMPLEQM.

       : ********************************************
       : *  Define the queues for Soccer            *
       : ********************************************
     1 : DEFINE QL('SOCCER_PUBLICATION')   REPLACE
AMQ8006: WebSphere MQ queue created.
     2 : DEFINE QL('SOCCER_SUBSCRIPTION') REPLACE
AMQ8006: WebSphere MQ queue created.
       :
       :
2 MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.
$

Creating a sample execution group

Execution groups are used to collect message flows to be run together in isolation from message flows in other execution groups. A single default execution group is created when you add a broker to a domain using the toolkit, but this is an optional step when using the Configuration Manager Proxy API. Therefore, use the following command to create an execution group specifically for the Soccer Results sample:

$ mqsicreateexecutiongroup -i localhost -p 1415 -q MQSI60_SAMPLEQM -b SAMPLE60_BK 
   -e soccer_sample
BIP1044I: Connecting to the Configuration Manager's queue manager...
Skipped Compiling {java/util/Hashtable}{rehash}
Skipped Compiling {java/util/Hashtable}{rehash}
BIP1045I: Connecting to the Configuration Manager...
BIP1124I: Creating execution group 'soccer_sample' on broker 'SAMPLE60_BK'...
BIP1126I: The execution group was created successfully.

The Configuration Manager will ask the broker to initialize the execution group when a resource 
   is deployed to it.
BIP8071I: Successful command completion.
$

Deploying the soccer message flow

The soccer message flow, as shown in Figure 2 below, contains just two nodes; an MQInput node and a Publication node. There are no system-specific properties in the broker archive (BAR) file for this message flow, so upi can deploy it directly using the mqsideploy command.

$ mqsideploy -i localhost -p 1415 -q MQSI60_SAMPLEQM -b SAMPLE60_BK 
   -e soccer_sample -a soccerresults.bar
BIP1044I: Connecting to the Configuration Manager's queue manager...
Skipped Compiling {java/util/Hashtable}{rehash}
Skipped Compiling {java/util/Hashtable}{rehash}
BIP1045I: Connecting to the Configuration Manager...
BIP1039I: Deploying BAR file '/home/jamest/verifymqsi/soccerresults.bar' to 
   broker 'SAMPLE60_BK' (execution group 'soccer_sample') ...
BIP1092I: Broker SAMPLE60_BK successfully processed the deployment request.
$

After you have deployed the Soccer message flow, the Soccer Results sample should be ready to run. The next section describes how to use the two applications that run the sample.

Verifying the sample configuration

It is finally time to find out whether everything really is working as it should. Two sample C applications, a results server and a match simulator, are provided with the run time to exercise the Soccer Results message flow. Precompiled copies are in <install_dir>/sample/soccer/bin, ready for use.

Starting the SoccerResults results server

The results server must be started first, so that it can register subscriptions before any games start. You only need to specify the queue manager to connect to, as show in Listing 9. After starting one or more games in the next step, the results service will start displaying the latest scores and, eventually, full-time results. It ends a short time after it stops receiving results.

$ soccerResults MQSI60_SAMPLEQM
Results Service is ready for match input,
instances of soccerGame can now be started.

Starting the SoccerGame game generator

The SoccerGame application simulates a match, publishing event information as goals are scored. You can start several games at the same time -- to start each new game, open a new command window and enter the command soccerGame <team1> <team2> <queue manager>:

$ soccerGame Brazil Germany MQSI60_SAMPLEQM
GOAL! Germany scores after 8 minutes
GOAL! Brazil scores after 9 minutes
GOAL! Germany scores after 11 minutes
GOAL! Brazil scores after 15 minutes
Full time
$

When you have started one or more games, check that the results service is displaying the latest scores, as shown in Listing 9. If the Soccer sample works correctly, you can be confident that the installation was successful.

Results Service is ready for match input,
instances of soccerGame can now be started.

LATEST: Brazil 0, Germany 1

LATEST: Brazil 1, Germany 1

LATEST: Brazil 1, Germany 2

LATEST: Brazil 2, Germany 2

FULLTIME: Brazil 2, Germany 2

Results Service has ended

$

Automating the process

The above procedure should enable you to verify any run-time system without installing the toolkit. But a manual process like this is more time-consuming and error-prone than using the wizards provided in the toolkit. This section shows you how to run the same verification automatically.

Adding a broker to the domain programmatically

The Configuration Manager Proxy API Exerciser was used to add the broker to the domain in the manual process. This is a sample application, so all the source code is available in <install_dir>/sample/ConfigManagerProxy/cmp/exerciser. Looking at ClassTesterForTopologyProxy.java shows how the steps taken in the API exerciser can be coded, as demonstrated in the basic class below. This source code is also provided in the accompanying zip file, inside verifymqsi.jar.

package com.ibm.uk.jamest;

import com.ibm.broker.config.proxy.BrokerProxy;
import com.ibm.broker.config.proxy.ConfigManagerProxy;
import com.ibm.broker.config.proxy.ConfigManagerProxyException;
import com.ibm.broker.config.proxy.MQConfigManagerConnectionParameters;
import com.ibm.broker.config.proxy.TopologyProxy;

/**
 * @see cmp.exerciser.ClassTesterForTopologyProxy
 */
public class AddSampleBroker
{

    public static void main(String[] args)
    {
        String configMgrQm = "MQSI60_SAMPLEQM";
        int configMgrPort = 1415;

        String brokerQm = "MQSI60_SAMPLEQM";
        String brokerName = "SAMPLE60_BK";

        System.out.println("Configuration Manager: Queue Manager="
                + configMgrQm + ", Server=localhost:"
                + Integer.toString(configMgrPort));
        System.out.println("Broker: Name=" + brokerName + ", Queue Manager="
                + brokerQm + "\n");

        if (args.length > 0)
        {
            System.out.println("Usage: AddSampleBroker does not take any arguments.");
            System.out
               .println("Rerun without any parameters to add the broker to the topology 
                 	using the details shown.\n");
            System.exit(0);
        }

        try
        {
            System.out.println("Connecting to configuration manager...");
            ConfigManagerProxy cmp = ConfigManagerProxy
                    .getInstance(new MQConfigManagerConnectionParameters(
                            "localhost", configMgrPort, configMgrQm));
            System.out.println("...connected.\n");

            System.out.println("Getting topology...");
            TopologyProxy t = cmp.getTopology();
            System.out.println("...ok.\n");

            System.out.println("Adding broker to topology...");
            BrokerProxy b = t.createBroker(brokerName, brokerQm);
            System.out.println("...broker added.\n");

            System.out.println("Creating default execution group...");
            b.createExecutionGroup("default");
            System.out.println("...execution group created.\n");
        }
        catch (ConfigManagerProxyException e)
        {
            System.out.println("...failed.\n");
            System.out.println(e.getLocalizedMessage());
            System.exit(1);
        }

    }

}

This code does just enough to replicate the manual steps described in the previous section, though there is room for improvement if you decide to go beyond simple install verification. For example, a more generic mqsiaddbroker command would complement other similar commands that already exist, such as mqsicreateexecutiongroup.

For background information on using the API, see "Developing applications that use the Configuration Manager Proxy Java API" in the WebSphere Message Broker information center. Javadoc is also available in <install_dir>/docs/ConfigManagerProxy.

Using a script to verify the installation

With a way to add the sample broker to the domain using the command line, writing a script to run the whole verification is now possible. The script verifyruntime.sh in the accompanying zip file shows how you might do this on Linux, using DB2 for the broker database. To avoid typing passwords in the clear, this script use the mqsi* command's ability to prompt for passwords, although it could easily be modified to run silently.

A complementary cleanupruntime.sh script is also provided to undo everything. It is designed to remove everything that is possible, without leaving the system in an unusual state. For example, it will not delete the queue manager if the broker could not be deleted for some reason. It can be rerun after solving any problems to complete the cleanup.

Troubleshooting

If you encounter any problems during the verification, see the "Dealing with problems" topics in the "Troubleshooting and support" section of the WebSphere Message Broker information center. You may also find the "Troubleshooting and problem determination" chapter of the WebSphere Message Broker Basics Redbook useful.

Conclusion

This article has shown you how to verify WebSphere Message Broker run-time installations without using the toolkit. After confirming that a basic configuration works, you can be confident of your ability to extend it. Knowing that the configuration manager is working, for example, will help you diagnose any problems when connecting from toolkits on remote systems.

The techniques described here are not limited to product verification. Configuring any system and deploying any message flow application can be done in the same way. BAR files contain deployment descriptors that can be used to override configurable properties in more complex message flows, enabling them to be deployed in a similar way to the simple Soccer Results message flow.

Acknowledgements

The author would like to thank Andy Piper and Rich Bicheno for their help in developing this article.

Back to top

Download

Description	Name	Size	Download method
Code samples in zip format	verifyruntime.zip	10 KB	FTP|HTTP

	Information about download methods

Resources

• WebSphere Message Broker Basics
  This IBM Redbook provides an overview of the latest release of WebSphere Message Broker and the Message Brokers Toolkit, including installation, developing simple message flows using ESQL, Java, and message maps, broker administration, debugging, and more.
  
  
• WebSphere Message Broker information center
  Documentation portal for WebSphere Message Broker, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
  
  
• Scripting deployment in WebSphere Business Integration Message Broker V5
  This article describes scripted deployment code that can simplify the maintenance and promotion of the WebSphere Business Integration Message Broker V5 code. The scripted deployment code allows you to automate and modify the BAR file's parameters, reducing the amount of manual intervention and errors.
  
  
• WebSphere Message Broker product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere Business Integration products page
  For both business and technical users, a handy overview of all WebSphere Business Integration products
  
  
• developerWorks WebSphere Business Integration zone
  For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Safari Bookshelf: e-library designed for developers
  Complete search and download access to thousands of technical books for a one-time subscription fee. Free trial for new subscribers.
  
  
• WebSphere forums
  Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
  
  
• developerWorks blogs
  Ongoing, free-form columns by software experts, to which you can add your comments. Check out Grady Booch's blog on software architecture.
  

About the author

		James Taylor is a Software Engineer at the IBM Hursley Software Lab in the UK. He worked on WebSphere MQ and WebSphere Message Broker for the past eight years, most recently as install architect for WebSphere Message Broker V6. He has recently moved to IBM Data Management. You can contact James at jamest@uk.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top