Sample: Point-to-point sample

Objectives
Demonstrates the use of Extended messaging support with a simple Point-to-Point sample.

Time required
To install and run the sample: 60 minutes.

Before you begin

Note: The infocenter documentation, as well as the MQ Series documentation, suggests copying jars and libraries from the MQSeries\java directory structure into various WebSphere directories. While this configuration may work, it is not recommended for serviceability reasons. Upgrades and patches to MQ Series will not take effect as desired.  Rather than copying files, follow the guidelines demonstrated in this sample documentation.

Information contained in this document, as well as the Release Notes provided with the product, supercedes any information contained in the Infocenter or MQ Series documentation.
Verify that you have the following software installed:

Ensure that MQSeries Server and its JMS support has been successfully installed.

The MQSeries JMS support is supplied as a supportPac (MA88) that is available as a Web download. The installation instructions for the supportPac are contained in the MQSeries Using Java guide (SC34-5456-06), also available from the MQSeries Web site:

http://www.ibm.com/software/ts/mqseries/txppacs/ma88.html

To test your MQSeries installation, run the JMS samples located in the /mq_install_dir/java/samples/jms directory. This procedure is described in the MQSeries InfoCenter Quick Beginnings, under the heading "Verifying a local installation".

Part 1: Define the MQ resources required by the sample
Use the standard RUNMQSC MQSeries tool to define the two local queues:

  1. Open a command window, and enter the following command to start the default queue manager (if not already started):

  2.  

     
     
     
     
     
     
     

    strmqm
     

  3. Enter the following command to start the utility (You should see a message, "Starting MQSeries Commands."  Note: There is no command prompt.):

  4.  

     
     
     
     
     
     
     

    runmqsc
     

  5. Define Q1 by entering the following command:

  6.  

     
     
     
     
     
     
     

    define Qlocal(Q1) put(enabled) get(enabled)
     

  7. Define Q2 by entering the following command:

  8.  

     
     
     
     
     
     
     

    define Qlocal(Q2) put(enabled) get(enabled)
     

  9. Use the following command to view and verify your queue definitions:

  10.  

     
     
     
     
     
     
     

    display Qlocal(Q*)
     

  11. Enter the following command to exit the utility:
  12. end

Part 2: Define JNDI resources
A sample configuration file (JMSppSetup.scp) defines the JNDI resources. Those resources are:

This sample uses the /Sample/JMS/ subcontext. If the subcontext already exists, the define (def) command generates an "unable to create context" error. You can ignore this error.

If you have already configured JMS, skip this procedure. Otherwise, complete the following steps to configure JMS support:

  1. In the command window, change to the JMS directory (for example, /mq_install_dir/java/bin).
  2. The JMSAdmin command utility, provided with MQ JMS support, requires that the correct INITIAL_CONTEXT_FACTORY value and PROVIDER_URL be specified. To verify these values, edit the JMSAdmin.config file according to the edition of WebSphere you have installed:
  3. Save the JMSAdmin.config file.
  4. Edit your JMSAdmin script as follows to ensure that it uses the version of Java provided by WebSphere and includes additional directories in its run time:

  5.  
  6. Before running any Java client accessing MQ Series, you need to add an entry to your java.library path to find the necessary libraries. Run the following before attempting to run the JMSAdmin tool:
  7.     PATH=%PATH%;mqm_install_dir\java\lib      (Windows) 
        export LIB_PATH=$LIB_PATH:mqm_install_dir/java/lib (AIX) 
        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:mqm_install_dir/java/lib (Solaris)
  8. Enter the following command to run the supplied script:
  9. JMSAdmin -cfg JMSAdmin.config < WAS_HOME/Enterprise/samples/messaging/src/PtoP/JMSppSetup.scp
    After running, verify the output contains no errors.
Part 3a: Enable Extended Messaging support on the server (AE)
Complete the following steps to enable Extended Messaging support on AE. If you are using AEd, go to Part 3b.
  1. Open a command window and change to the WAS_HOME/bin directory.
  2. Start the administrative server. If the server is active, stop and restart it as follows:
  3. Start the administrative console.
  4. In the administrative console, select Resources > JMS Providers.
  5. Right click on JMS Providers and select New.
  6. On the General Property tab, specify the following:

  7. Name: MQProvider
    Context Factory: com.ibm.websphere.naming.WsnInitialContextFactory
    Provider URL:iiop://localhost/
  8. On the Nodes tab, specify the following:

  9. Select Install New...
    Select your node
    Select Specify Driver...
    Select Add Driver...
    Navigate to your mqm_install_dir\java\lib directory and select com.ibm.mq.jar, select Open
    Select Add Driver...
    Navigate to your mqm_install_dir\java\lib directory and select com.ibm.mqjms.jar, select Open
    Select Set
    Select Install
    Select OK
  10. Expand the JMS provider (MQProvider) that you just created and add your Connection Factory and Destinations.
    1. Select JMS Connection Factories and click New. Specify the following values:

    2. Name: ConnectionFactory
      External JNDI path: Sample/JMS/QCF
      Select OK
       
    3. Select JMS Destinations and click New. Specify the following values:

    4. Name: Q1
      External JNDI path: Sample/JMS/Q1
      Select OK
       
    5. Click New again and specify the following values:

    6. Name: Q2
      External JNDI path: Sample/JMS/Q2
      Select OK
  11. Manually enable the Extended Messaging service as follows:
    1. In the administrative console, expand Nodes > your_node.
    2. Right click on Application Servers and select New. Create a new application server called PtoPSrv. Click OK.
    3. Your server should appear under the Application Server, select it, then select the Custom tab.
    4. Select Extended Messaging Support Service and click Edit.
    5. Enter the following Configuration File URL:

    6. WAS_HOME/Enterprise/samples/messaging/src/PtoP/jmsconfig.xml
    7. Specify a classpath of

    8. <mq_install_dir>/java/lib/com.ibm.mq.jar:<mq_install_dir>/java/lib/com.ibm.mqjms.jar
    9. Ensure that Enabled is selected. Click OK, then click Apply.
    Note:
    If you want to install both of the Extended messaging samples concurrently, you must produce a new jmsconfig.xml file. This file will need to contain the definitions for both sample configuration files.
Part 3b: Enable Extended Messaging support on the server (AEd)
Complete the following steps to enable Extended Messaging support on AEd:
  1. Open a command window and change to the WAS_HOME/bin directory.
  2. Start the administrative server. If the server is active, stop and restart it as follows:
  3. Start the administrative console by entering the following URL in your Web browser:

  4.  

     
     
     
     
     
     
     

    http://your_host_name:9090/admin

    Browse the tree for Resources > JMS Providers.

    Select JMS Providers and click New. Specify the following values:

    Server Class Path: Type the following line, where mq_install_dir is the directory where MQSeries was installed.

    Note: The lines are split here for readability; on Windows platforms, the separator is a semicolon (;) not a colon (:).

      /mq_install_dir/java/lib/fscontext.jar:
    
      /mq_install_dir/java/lib/providerutil.jar:
    Name: MQProvider
    Context Factory: com.sun.jndi.fscontext.RefFSContextFactory
    Provider URL: file:/directory_path

    Note: For information about directory_path, see Part 2.

  5. Click OK, and then save your changes to the provider.
  6. Expand the JMS provider (MQProvider) that you just created, and add your Connection Factory and Destinations. Adding these provides foreign references from the WebSphere name space to the File System name space.
    1. Select JMS Connection Factories and click New. Specify the following values:

    2.  

       
       
       
       
       
       
       

      Name: ConnectionFactory
      JNDI Name: Sample/JMS/QCF
      External JNDI Name: Sample/JMS/QCF (Sample\JMS\QCF on Windows systems)
      Connection Type: Queue
      Click OK
       

    3. Select JMS Destinations and click New. Specify the following values:

    4.  

       
       
       
       
       
       
       

      Name: Q1
      JNDI Name: Sample/JMS/Q1
      External JNDI Name: Sample/JMS/Q1 (Sample\JMS\Q1 on Windows systems)
      Destination Type: Queue
      Click OK
       

    5. Click New again and specify the following values:

    6.  

       
       
       
       
       
       
       

      Name: Q2
      JNDI Name: Sample/JMS/Q2
      External JNDI Name: Sample/JMS/Q2 (Sample\JMS\Q2 on Windows systems)
      Destination Type: Queue

      Click OK

  7. Manually enable the Extended Messaging Service as follows
    1. From the administrative console, expand the Nodes > your_node and Applications Servers > Default Server. Click Custom Services.
    2. Select Extended Messaging Support Service.
    3. In theExternal Config URL field, type the following path:

    4.  

       
       
       
       
       

      WAS_HOME/Enterprise/samples/messaging/src/PtoP/jmsconfig.xml

    5. Specify a classpath of

    6.  

       
       
       
       
       

      <mq_install_dir>/java/lib/com.ibm.mq.jar:<mq_install_dir>/java/lib/com.ibm.mqjms.jar (Unix)
      <mq_install_dir>\java\lib\com.ibm.mq.jar;<mq_install_dir>\java\lib\com.ibm.mqjms.jar (Windows)

    7. Click OK.
    8. Save your configuration.
Part 4a: Install the application (AE)
Complete the following steps to install the ear file on AE, thereby installing the application. If you are using AEd, go to Part 4b.
  1. In the administrative console, select Wizards > Install Enterprise Application.
  2. Select your node and select the Install Application (*.ear)
  3. Click Browse and open the following file:

  4. WAS_HOME/Enterprise/samples/messaging/src/PtoP/JMSPPSampleEJB.ear
  5. Click Next on each of the subsequent panels until you reach the Mapping Resource References to Resources panel.
  6. The SamplePPQCF should already be set to "jms/Connection Factory". Select SampleOutputQueue, then click Select Resource. From the pulldown list select Q2 and click OK.
  7. Click Next until you arrive at the Selecting the Application Server panel.
  8. Click Select Server. Select the server you created (PtoPSrv)and click OK.
  9. Click Next, click Finish, answer Yes to the popup, then click OK to deploy the application. The application is added to the Enterprise Applications list.
  10. Ensure that the default queue manager is running, then start your PtoPSrv application server.
Part 4b: Install the application (AEd)
Complete the following steps to install the ear file on AEd:
  1. In the administrative console, select Nodes > your_node > Enterprise Applications.
  2. Click Install.
  3. Click Browse, and open the following file:

  4. WAS_HOME/Enterprise/samples/messaging/src/PtoP/JMSPPSampleEJB.ear
  5. Continue to click Next until you reach the Mapping Resource References to JNDI Names panel.
  6. For jms/SamplePPQCF, enter Sample/JMS/QCF.
  7. For jms/SampleOutputQueue, enter Sample/JMS/Q2. Click Next until you reach the final confirmation panel. Click Finish to deploy the application. The application is added to the Enterprise Applications list.
  8. Save your configuration.
  9. Stop and restart the server. Before restarting the server ensure that the default queue manager is running.
Part 5: Run the sample
The sample client application takes two arguments as follows:
JMSppSampleClient [-verbose] -msg "MessageText"
The optional -verbose parameter causes the client to report its progress. The -msg parameter must be specified.

To simplify the running of this sample, a batch file (RunPPClient) is provided, which takes a single argument, the "message text". For example:

RunPPClient "A message to send and receive"
Before using the batch file, verify that the path values defined in the command are valid:
  1. Change directory to WAS_HOME/Enterprise/samples/messaging/src/PtoP.
  2. Edit the RunPPClient script to use the WebSphere-supplied Java 2 SDK, and to specify additional directories to be included in the run time search:
To run the sample, perform the following steps:
  1. Start the Server. If is already started, stop the server and restart it.
  2. At a command prompt, enter the following command to invoke the sample:

  3. Note: Before starting, modify your java.library.path as you did before running JMSAdmin. See Part 2, step 5.
    RunPPClient "A message to send and receive"
    The JMS client sends the message as described above, and reports its progress. The output is similar to the following:
    Sending message: 'A message to send and receive'
    Retrieving a QueueConnectionFactory from JNDI
    Retrieving Queues from JNDI
    Creating a Connection
    >Starting the Connection
    Creating a Session
    Creating a QueueSender
    Creating a TextMessage
    Unable to load message catalog - mqji
    Sending the message to queue:///Q1
    Creating a QueueReceiver
    JMSCorrelationID = 'ID:414d5120514d5f77736631303020202037243e3b12600000'
    Receiving message from queue:///Q2
    Retrieving the message
    
    Got message:
    JMS Message class: jms_text
     JMSType:  null 
     JMSDeliveryMode: 2 
     JMSExpiration:   0
     JMSPriority:     4
     JMSMessageID: ID:414d5120514d5f77736631303020202037243e3b12700000
     JMSTimestamp:  993936363600
     JMSCorrelationID:ID:414d5120514d5f77736631303020202037243e3b12600000
     JMSDestination:  queue:///Q2
     JMSReplyTo:     null
     JMSRedelivered:  false
     JMSXAppID:\AppServer\java\bin\java.exe
     JMS_IBM_Format:MQSTR
     JMS_IBM_PutApplType:11
     JMS_IBM_MsgType:8
     JMSXUserID:userid
     JMSXDeliveryCount:1
    A message to send and receive
    Reply string equals original string
    Closing QueueReceiver
    Closing QueueSender
    Closing Session
    Closing Connection
    End of Sample


    Check the application server's Standard output and Standard error files to ensure there are no error messages generated from the server.