Writing Java tests for your WebSphere MQ environment to use in MQ Explorer

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin
   id="com.ibm.mq.explorer.healthcheck.samples"
   name="Custom WebSphere MQ Tests"
   version="1.0.0"
   provider-name="IBM developerWorks"
   class="com.ibm.mq.explorer.healthcheck.samples.SamplesPlugin">

   <runtime>
      <library name="samples.jar">
         <export name="*"/>
      </library>
   </runtime>

   <requires>
      <import plugin="org.eclipse.ui"/>
      <import plugin="org.eclipse.core.runtime"/>
      <import plugin="com.ibm.mq.commonservices"/>
      <import plugin="com.ibm.mq.explorer.core"/>
      <import plugin="com.ibm.mq.explorer.healthcheck"/>
      <import plugin="com.ibm.mq.explorer.plugins"/>
      <import plugin="com.ibm.mq.explorer.ui"/>
      <import plugin="com.ibm.mq.internal.pcf"/>
      <import plugin="com.ibm.mq.internal.pcf.event"/>
      <import plugin="com.ibm.mq.runtime"/>
      <import plugin="org.eclipse.core.resources"/>
   </requires>
   <extension point="com.ibm.mq.explorer.healthcheck.MQtests">
      <test
         furtherinfo="doc/QueueNamesInfo.html"
         class="com.ibm.mq.explorer.healthcheck.samples.QueueNames"
         description="A sample test to check queue names against simple naming conventions."
         testset="Queues"
         name="Naming Conventions"
         id="com.ibm.mq.explorer.healthcheck.samples.QueueNames"/>
   </extension>
</plugin>

package com.ibm.mq.explorer.healthcheck.samples;

import com.ibm.mq.explorer.healthcheck.objects.WMQTest;

/**
 * Empty test class - enough to compile.
 *
 * @author Dale Lane
 */
public class QueueNames extends WMQTest {

}

package com.ibm.mq.explorer.healthcheck.samples;

import java.util.ArrayList;

import org.eclipse.core.resources.IMarker;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;

import com.ibm.mq.explorer.healthcheck.HealthcheckPlugin;
import com.ibm.mq.explorer.healthcheck.actions.WMQTestEngine;
import com.ibm.mq.explorer.healthcheck.objects.WMQTest;
import com.ibm.mq.explorer.healthcheck.objects.WMQTestResult;

/**
 * A sample skeleton implementation of a Healthcheck test.
 *
 * Download the source from Resources below.
 *
 * @author Dale Lane
 */
public class QueueNames extends WMQTest {

    // notice that no constructor is required

    /**
     * Starts the test.
     *
     * @param callback     handle to the test engine running the test
     * @param guimonitor  handle to the object monitoring the test,
     *                      provided to allow the test to periodically check
     *                      if the user has tried to cancel the test running
     *                      and provide additional user feedback
     */
    public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor) {

        // start with the default implementation. this will store a handle
        // to the test engine that will be needed when we want to submit
        // any results at the end of the test
        super.runTest(callback, guimonitor);

        // start the progress monitor for this test
        String myName = getTestName();
        guimonitor.beginTask(myName, 10);
        guimonitor.subTask("Getting preferences for test");

        // prepare space to store any results we might want to return
        ArrayList testResults = new ArrayList();

        // generate nine meaningless test results
        for ( int i=0; i < 9; i++ ) {

            // update progress monitor
            guimonitor.subTask("Generating test result " + i + " of 9");

            // if the test has been cancelled, we break out of the
            //      for loop to return asap
            if ( isCancelled() )
                break;

            try {
                // wait here for two seconds to simulate lengthy test processing
                Thread.sleep(2000);
            } catch ( InterruptedException e ) {
                // unexpected exception
                Status internal_error = new Status(IStatus.ERROR,
                                        "com.ibm.mq.explorer.healthcheck.coretests",
                                        0,
                                        "Unexpected exception encountered while "
                                        + "waiting for test to return",
                                        e);
                HealthcheckPlugin.getPlugin().getLog().log(internal_error);
            }

            // create a fake result and add it to the list
            WMQTestResult nxtResult = new WMQTestResult(IMarker.SEVERITY_INFO, 
                                         "Blah blah blah test result number "
                                         + i + " here",
                                         "QMGR_1",
                                         "Queues");
            testResults.add(nxtResult);

            // increment progress monitor
            guimonitor.worked(1);
        }

        // update progress monitor
        guimonitor.subTask("Returning results to test engine");

        // return any results that this test has generated
        WMQTestResult[] finalresults = 
            (WMQTestResult[]) testResults.toArray(new WMQTestResult[testResults.size()]);
        testComplete(finalresults);

        // complete progress monitor
        guimonitor.done();
    }
}

package com.ibm.mq.explorer.healthcheck.samples;

import java.io.IOException;
import java.util.ArrayList;

import org.eclipse.core.resources.IMarker;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;

import com.ibm.mq.MQException;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.explorer.healthcheck.HealthcheckPlugin;
import com.ibm.mq.explorer.healthcheck.PreferenceStoreManager;
import com.ibm.mq.explorer.healthcheck.actions.WMQTestEngine;
import com.ibm.mq.explorer.healthcheck.objects.WMQTest;
import com.ibm.mq.explorer.healthcheck.objects.WMQTestResult;
import com.ibm.mq.explorer.ui.extensions.MQQmgrExtObject;
import com.ibm.mq.explorer.ui.internal.objects.ExplorerExtensionBase;
import com.ibm.mq.pcf.CMQC;
import com.ibm.mq.pcf.CMQCFC;
import com.ibm.mq.pcf.PCFMessage;
import com.ibm.mq.pcf.PCFMessageAgent;

/**
 * A sample test used to check Queue Names against naming conventions.
 * Queue names are checked if they begin with any of a set range of
 * prefixes, defined in this class. Any names which do not start with
 * one of the prefixes are output in an error.
 *
 * Download the source from Resources below.
 *
 * @author Dale Lane
 */
public class QueueNames extends WMQTest {

    /** Maintain a count of how many queue managers we are waiting for replies from. */
    private static int numberOfQmgrs = 0;

    /** Stores the accepted queue name prefixes. */
    private static final String[] ACCEPTED_Q_PREFIXES = { "SALES_",
                                                          "MARKETING_",
                                                          "SHIPPING_",
                                                          "INCOMING_",
                                                          "OUTGOING_" };

    /** Stores the user preference for whether hidden queue managers should be included. */
    boolean includeHiddenQmgrs = false;

    /** Stores the user preference for whether system queues should be included. */
    boolean includeSystemObjs  = false;

    /**
     * Starts the test.
     *
     * @param callback    handle to the test engine running the test
     * @param guimonitor  a handle to the object monitoring the test,
     *                    provided to allow the test to periodically check
     *                    if the user has tried to cancel the test running
     *                    and provide additional user feedback
     */
    public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor) {

        // start with the default implementation. this will store a handle
        //  to the test engine that will be needed when we want to submit
        //  any results at the end of the test
        super.runTest(callback, guimonitor);

        // prepare space to store any results we might want to return
        ArrayList testResults = new ArrayList();

        // get from Preferences whether we should include hidden queue managers
        includeHiddenQmgrs = PreferenceStoreManager.getIncludeHiddenQmgrsPreference();
        // get from Preferences whether we should include system queues
        includeSystemObjs  = PreferenceStoreManager.getIncludeSysObjsPreference();

        // get a list of queue managers from the Explorer
        ArrayList allQmgrs;

        if (includeHiddenQmgrs){
            allQmgrs = ExplorerExtensionBase.getAllQueueManagers();
        }
        else {
            allQmgrs = ExplorerExtensionBase.getShownQueueManagers();
        }

        // how many queue managers are there?
        numberOfQmgrs = allQmgrs.size();

        // use the number of queue managers as a guide to track progress
        guimonitor.beginTask(getTestName(), numberOfQmgrs);

        // for each queue manager, submit a query
        for (int i=0; i < numberOfQmgrs; i++){

            // get next queue manager
            MQQmgrExtObject nextQueueManager = (MQQmgrExtObject) allQmgrs.get(i);

            // only submit queries to connected queue managers
            if (nextQueueManager.isConnected()){

                // get the name of the queue manager, for use in GUI
                String qmgrName = nextQueueManager.getName();

                // get a handle to a Java object representing the queue manager
                MQQueueManager qmgr = nextQueueManager.getMQQueueManager();

                try {
                    // get a PCF message agent to handle sending PCF inquiry to
                    PCFMessageAgent agent = new PCFMessageAgent(qmgr);

                    // use PCF to submit an inquire queue names query
                    PCFMessage response = submitQueueNamesQuery(qmgrName, agent);

                    // did we get a response to the query?
                    if (response != null){
                        // get the queue names out of the reply
                        String[] qnames = (String[]) response.getParameterValue(CMQCFC.MQCACF_Q_NAMES);

                        // check each name
                        for (int j=0; j < qnames.length; j++){
                            boolean qnameOkay = checkQueueName(qnames[j]);

                            if (!qnameOkay){
                                // if a problem was found with the name, we generate an
                                //  error message, and add it to the collection to be
                                //  returned
                                testResults.add(generateTestResult(qnames[j], qmgrName));
                            }
                        }
                    }
                } catch (MQException e) {
                    // record error details
                    Status internal_error = new Status(
                            IStatus.ERROR,
                            "com.ibm.mq.explorer.healthcheck.coretests",
                            0,
                            "Error encountered while getting PCFMessageAgent to "
                                + qmgrName,
                            e);
                    HealthcheckPlugin.getPlugin().getLog().log(internal_error);
                }
            }

            // finished examining a queue manager
            guimonitor.worked(1);
        }

        // return any results that this test has generated
        WMQTestResult[] finalresults = 
            (WMQTestResult[]) testResults.toArray(new WMQTestResult[testResults.size()]);
        testComplete(finalresults);
    }

     
    /**
     * Used internally to submit INQUIRE_Q_NAMES query using PCF to given queue manager
     *
     * @param qmgrName   name of queue manager to submit query to
     * @param agent
     * @return          PCF response from queue manger
     */
    private PCFMessage submitQueueNamesQuery(String qmgrName, PCFMessageAgent agent){

        // build the pcf message
        PCFMessage inquireQNames = new PCFMessage(CMQCFC.MQCMD_INQUIRE_Q_NAMES);
        inquireQNames.addParameter(CMQC.MQCA_Q_NAME, "*");

        try {
            // send the message
            PCFMessage[] responseMsgs = agent.send(inquireQNames);

            // check if results received successfully
            if ( responseMsgs[0].getCompCode() == 0 ) {
                return responseMsgs[0];
            }
        } catch (IOException e) {
            // record error details
            Status internal_error = new Status(
                    IStatus.ERROR,
                    "com.ibm.mq.explorer.healthcheck.coretests",
                    0,
                    "Error encountered while sending INQUIRE_Q_NAMES PCF to "
                        + qmgrName,
                    e);
            HealthcheckPlugin.getPlugin().getLog().log(internal_error);

        } catch (MQException e) {
            // record error details
            Status internal_error = new Status(
                    IStatus.ERROR,
                    "com.ibm.mq.explorer.healthcheck.coretests",
                    0,
                    "Error encountered while sending INQUIRE_Q_NAMES PCF to "
                        + qmgrName,
                    e);
            HealthcheckPlugin.getPlugin().getLog().log(internal_error);
        }

        // for some reason, we don't have a response, so return null
        return null;
    }

     
    /**
     * Used internally to check the given queue name against the collection
     * of acceptable prefixes.
     *
     * @param queueName    queue name to check
     * @return          true if queue name is okay,
     *                    false otherwise
     */
    private boolean checkQueueName(String queueName){

        // if this is a system object (i.e. it has a name which begins with
        //   "SYSTEM.") we check the
        if ((queueName.startsWith("SYSTEM.")) || (queueName.startsWith("AMQ."))){
            if (!includeSystemObjs){
                // user has requested that we do not include system
                // objects in the test, so we return true to
                // avoid any problems being reported for this queue
                return true;
            }
        }

        // PCF response will white-pad the queue name, so we trim it now
        queueName = queueName.trim();

        // check the queue name against each of the acceptable prefixes
        //  in turn, returning true immediately if it is
        for (int i=0; i < ACCEPTED_Q_PREFIXES.length; i++){
            if (queueName.startsWith(ACCEPTED_Q_PREFIXES[i]))
                return true;
        }

        // we have checked against all accepted prefixes, without
        //  finding a match
        return false;
    }

    
    /**
     * Used internally to generate a test result for the given queue name.
     *
     * @param queueName    queue name that doesn't meet requirements
     * @param qmgrName     name of queue manager that hosts the queue
     * @return         generated test result
     */
    private WMQTestResult generateTestResult(String queueName, String qmgrName){
        return new WMQTestResult(IMarker.SEVERITY_ERROR,
                                 "Queue (" + queueName.trim() + ") "
                                    + "does not begin with "
                                    + "a known prefix",
                                 qmgrName,
                                 "Queues");
    }
}

    Status internal_error = new Status(IStatus.ERROR,
                                       "com.ibm.mq.explorer.healthcheck.coretests",
                                       0,
                                       "Error encountered while doing something",
                                       event.getException());
    HealthcheckPlugin.getPlugin().getLog().log(internal_error);

package com.ibm.mq.explorer.healthcheck.samples;

import java.util.ArrayList;

import org.eclipse.core.resources.IMarker;
import org.eclipse.core.runtime.IProgressMonitor;

import com.ibm.mq.explorer.healthcheck.HealthcheckPlugin;
import com.ibm.mq.explorer.healthcheck.PreferenceStoreManager;
import com.ibm.mq.explorer.healthcheck.actions.WMQTestEngine;
import com.ibm.mq.explorer.healthcheck.objects.WMQTestResult;
import com.ibm.mq.pcf.CMQC;

/**
 * Pseudo-code sample demonstrating an asynchronous approach to implementing a
 * Healthcheck test.
 *
 * @author Dale Lane
 */
public class QueuesTest extends WMQTest implements SomeListener {

    /** Used to store test results. */
    private ArrayList testresults = new ArrayList();

    /**
     * Used to start the test.
     *
     * @param callback     handle to the test engine running the test
     * @param guimonitor    handle to the object monitoring the test,
     *                     provided to allow the test to periodically check
     *                     if the user has tried to cancel the test running
     */
    public void runTest(WMQTestEngine callback, IProgressMonitor guimonitor) {

        super.runTest(callback, guimonitor);

        // reset all test stores
        testresults = new ArrayList();

        // initialise the progress bar part of the GUI used to show progress of
        //  this test
        guimonitor.beginTask(getTestName(), numqmgrs);

        // start the test!

        // send query
        PseudoQueueManager qmgrHandle = pseudoGetQueueManager();
        submitQmgrQuery(qmgrHandle, this, query);

        // note that the runTest method is now finished, but the test is not over!
    }


    /**
     * Used to process results received in response to query submitted by runTest.
     *
     * @param objects          data received
     */
    public void dataReponseReceived(ArrayList objects) {

        // analyse each of the replies in the collection received in the reply
        for ( int i = 0; i < objects.size(); i++ ) {
            PseudoQueue nxtQueue = (PseudoQueue) objects.get(i);
            analyseQueue(nxtQueue);

            // increment GUI progress bar used to show progress of this test
            getGUIMonitor().worked(1);
        }

        // now that we have got the data that we were waiting for, and have
        //  finished processing it, the test has really finished - we are
        //  nearly ready to call testComplete to mark the test finished

        // return the completed results
        WMQTestResult[] finalresults = 
            (WMQTestResult[]) testresults.toArray(new WMQTestResult[0]);
        testComplete(finalresults);
    }

    /**
     * Analyse the given queue. If any potential problems are found, a problem
     * marker is added to the testresults collection.
     *
     * @param queue       queue to analyse
     */
    private void analyseQueue(PseudoQueue queue) {

        // do something

        // add a problem marker to the collection
        if (problemFound) {
            testresults.add(new WMQTestResult(IMarker.SEVERITY_WARNING,
                                              "A problem was found with "
                                                + queueName,
                                              getQueueManagerName(queue),
                                              "Queues"));
        }
    }
}

Dale Lane is a software engineer on the WebSphere MQ System Test team at the IBM Hursley Software Lab in the UK. Dale earned a Bachelor of Science degree in Computer Science at the University of Bath, UK, and is a Sun Java 2 Certified Programmer and IBM Certified WebSphere MQ System Administrator. You can contact Dale at dale.lane@uk.ibm.com.