Verifying the resource adapter installation

The installation verification test (IVT) program for the IBM® MQ resource adapter is supplied as an EAR file. To use the program, you must deploy it and define some objects as JCA resources.

About this task

The installation verification test (IVT) program is supplied as an enterprise archive (EAR) file called wmq.jmsra.ivt.ear. This file is installed with IBM MQ classes for JMS in the same directory as the IBM MQ resource adapter RAR file, wmq.jmsra.rar. For information about where these files are installed, see Installing the IBM MQ resource adapter.

You must deploy the IVT program on your application server. The IVT program includes a servlet and an MDB that tests that a message can be sent to, and received from, an IBM MQ queue. You can use the IVT program to verify that the IBM MQ resource adapter has been correctly configured to support distributed transactions. If you are deploying the IBM MQ resource adapter in an non-IBM application server, IBM Service might ask you to demonstrate the IVT working to validate that your application server is correctly configured.

Before you can run the IVT program, you must define a ConnectionFactory object, a Queue object and possibly an Activation Specification object as JCA resources, and ensure that your application server creates JMS objects from these definitions and binds them into a JNDI namespace. You can choose the properties of the objects to match the host and port settings of your own QueueManager, but the following set of properties is a simple example: 
ConnectionFactory object:
channel:              SYSTEM.DEF.SVRCONN
hostName:             localhost
port:                 1550
queueManager:         QM1
transportType:        CLIENT
Queue object:
baseQueueManagerName: QM1
baseQueueName:        TEST.QUEUE
The mechanism used to define the ConnectionFactory, Queue and Activation Specification objects varies depending on your application server. For example, to set these properties within WebSphere® Application Server Liberty, add the following entries to the application server's server.xml file:
<!-- IVT Connection factory -->
<jmsQueueConnectionFactory connectionManagerRef="ConMgrIVT" jndiName="IVTCF">
   <properties.wmqJms channel="SYSTEM.DEF.SVRCONN" hostname="localhost" port="1550" transportType="CLIENT"/>
</jmsQueueConnectionFactory>
<connectionManager id="ConMgrIVT" maxPoolSize="10"/>

<!-- IVT Queues -->
<jmsQueue id="IVTQueue" jndiName="IVTQueue">
   <properties.wmqJms baseQueueName="TEST.QUEUE"/>
</jmsQueue>

<!-- IVT Activation Spec -->
<jmsActivationSpec id="wmq.jmsra.ivt/WMQ_IVT_MDB/WMQ_IVT_MDB">    
   <properties.wmqJms destinationRef="IVTQueue"
transportType="CLIENT"
queueManager="QM1"
hostName="localhost"
port="1550"
maxPoolDepth="1"/>
</jmsActivationSpec>

By default, the IVT program expects a ConnectionFactory object to be bound in the JNDI namespace with the name jms/ivt/IVTCF and a Queue object to be bound with the name jms/ivt/IVTQueue. You can use different names, but if you do, you must enter the names of the objects on the initial page of the IVT program and modify the EAR file appropriately.

After you have deployed the IVT program, and the application server has created the JMS objects and bound them into the JNDI namespace, you can start the IVT program by completing the following steps.

Procedure

  1. Start the IVT program by entering a URL in the following format into your web browser: 
    
http://app_server_host: port/WMQ_IVT/
    where app_server_host is the IP address or host name of the system on which your application server is running, and port is the number of the TCP port on which the application server is listening. Here is an example: 
    
http://localhost:9080/WMQ_IVT/
    Figure 1 shows the initial page of the IVT program.
    Figure 1. The initial page of the IVT program
    The figure shows the initial page of the IVT program. The page contains a field labeled "Connection Factory", which is initialized to "IVTCF", and a field labeled "Destination", which is initialized to "IVTQueue". Following these fields is a check box labeled "Transactional Test", which has been selected. The check box is followed by a field labeled "Transactional EJB Name", which is initialized to "ejb/ejbs/WMQ_TransactedIVT". At the bottom of the page are two push buttons, one labeled "Run IVT" and the other labeled "Reset Values".
  2. To run the test, click Run IVT.
    Figure 2 shows the page that is displayed if the IVT is successful.
    Figure 2. Page showing the results of a successful IVT
    The figure shows a page of the IVT program for a successful test. At the top of the page are two messages: "Using Connection Factory: IVTCF" and "Using Destination: IVTQueue". These messages are followed by a sequence of messages indicating the progress of the IVT. Each message in the sequence has a check mark to the right of it. The messages in the sequence are: "Creating initial context ...", "Looking up MQ Connection Factory ... (Altered JNDI name to java:IVTCF)", "Looking up Destination ...", "Creating connection ...", "Starting connection ...", "Creating session ...", "Creating message consumer ...", "Creating message producer ...", "Creating message ...", Sending message ...", "Receiving message ...", "Closing connection ...", and "Attempting transacted test ... (Altered JNDI name to WMQ_TransactedIVT)". These messages are followed by a further message in bold stating that the IVT completed successfully. At the bottom of the page is a push button labeled "View Message Contents", followed by a link labeled "Re-run Installation Verification Test".
    If the IVT fails, a page like that shown in Figure 3 is displayed. To obtain further information about the cause of the failure, click View Stack Trace.
    Figure 3. Page showing the results of an IVT that failed
    The figure shows a page of the IVT program for a test that failed. At the top of the page are two messages: "Using Connection Factory: java:IVTCF" and "Using Destination: IVTQueue". These messages are followed by a sequence of messages indicating the progress of the IVT. Each message in the sequence has a check mark to the right of it. The messages in the sequence are: "Creating initial context ...", "Looking up MQ Connection Factory ...", "Looking up Destination ...", "Creating connection ...", "Starting connection ...", and "Creating session ...". A final message in the sequence then states "Creating message consumer ... failed to create message consumer!", and this message has a white cross in a red circle to the right of it. Following the sequence of messages is a message in bold stating that the IVT failed. This message is followed by another message, which states "Error received - JMS Exception: javax.jms.JMSException: MQJMS2008: failed to open MQ queue". This message is followed by a push button labeled "View Stack Trace", which is followed by a repeat of the message stating that the IVT failed. At the bottom of the page are two links, one labeled "Retry Installation Verification Test" and the other labeled "Change IVT parameters".