Sample: Publish/Subscribe sample

Objectives
Demonstrates the use of Extended messaging support with a simple Publish/Subscribe 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, its JMS support, and its Publish/Subscribe support have 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
The MQSeries Publish/Subscribe support is supplied as a supportPac (MA0C) that is available as a Web download from the MQSeries Web site:
http://www.ibm.com/software/ts/mqseries/txppacs/ma0c.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 JMS publish/subscribe sample
If you have already configured JMS together with the Publish/Subscribe support you can skip this step. Otherwise complete the following steps to configure JMS and Publish/Subscribe support for use with WebSphere.

The publish/subscribe supportPAC requires a number of system-defined MQ resources to be defined to the MQSeries server. The definitions for these resources are contained in the MQJMS_PSQ.mqsc file, which is supplied with the supportPACs. You can use the MQSeries RUNMQSC tool to define the required resources as follows:

  1. Open a command window and change to the directory where the MQJMS_PSQ.mqsc file is installed (for example, mq_install_dir/java/bin).
  2. Enter the following command:
  3. runmqsc < MQJMS_PSQ.mqsc
Part 2: Define JNDI resources
A sample configuration file (JMSpsSetup.scp) is supplied to define the JNDI resources. Those resources are: The sample uses the /Sample/JMS/ subcontext. If the subcontext already exists, the define command (def) 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. Before running any Java client accessing MQ Series, you need to add an entry to your java.library path to find the necessary libraries. Update your path environment variable as follows before attempting to run the JMSAdmin tool:

  6.  

     
     
     

    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)
     

  7. Ensure your WebSphere Server has been started, then enter the following command to run the supplied script:
  8. JMSAdmin -cfg JMSAdmin.config <
      /WAS_HOME/Enterprise/samples/messaging/src/PubSub/JMSpsSetup.scp
Part 3: Controlling the broker
The MQSeries Publish/Subscribe User's Guide provides complete information about how to control the broker. The following is an overview. Part 4a: 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 4b.
  1. Open a command window and change to the WAS_HOME/bin directory.
  2. Start the administrative server.
  3. Start the administrative console. If the server is active, stop and restart it as follows:
Part 4b: 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. Note: Before starting, modify your java.library.path as you did before running JMSAdmin. See Part 2, step 5.
  4. Start the administrative console by entering the following URL in your Web browser:

  5.  

     
     
     
     
     

    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.

  6. Click OK, and then save your changes to the provider.
  7. 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. Use the same names as specified to the JMSAdmin command. See the earlier note for use of FSContexts with Windows systems.
    1. Select JMS Connection Factories and click New. Specify the following values:

    2.  

       
       
       

      Name: ConnectionFactory1
      JNDI Name: Sample/JMS/TCF
      External JNDI Name: Sample/JMS/TCF
      Connection Type: Topic

      Click OK

    3. Click New again and specify the following values:

    4.  

       
       
       
       
       

      Name: ConnectionFactory2
      JNDI Name: Sample/JMS/TCFBean
      External JNDI Name: Sample/JMS/TCFBean
      Connection Type: Topic

      Click OK

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

    6.  

       
       
       
       
       

      Name: T1
      JNDI Name: Sample/JMS/listen
      External JNDI Name: Sample/JMS/listen
      Destination Type: Topic

      Click OK

    7. Click New again and specify the following values:

    8.  

       
       
       
       
       

      Name: T2
      JNDI Name: Sample/JMS/news
      External JNDI Name: Sample/JMS/news
      Destination Type: Topic

      Click OK

    9. Click New again and specify the following values:

    10.  

       
       
       
       
       

      Name: T3
      JNDI Name: Sample/JMS/sport
      External JNDI Name: Sample/JMS/sport
      Destination Type: Topic

      Click OK

    11. Click New again and specify the following values:

    12.  

       
       
       
       
       

      Name: T4
      JNDI Name: Sample/JMS/weather
      External JNDI Name: Sample/JMS/weather
      Destination Type: Topic

      Click OK

  8. 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/PubSub/jmsconfigPS.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

    7. Click OK.
    8. Save your configuration.
Part 5a: 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 5b.
  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/PubSub/JMSPSSampleEJB.ear

  5. Click Next on each of the subsequent panels until you reach the Selecting the Application Server panel.
  6. Click Select Server. Select the server you created (PubSub)and click OK.
  7. 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.
  8. Ensure that the default queue manager is running, then start your PubSub application server.
Part 5b: 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/PubSub/JMSPSSampleEJB.ear

  5. Continue to click Next until you reach the final panel. Click Finish to deploy the application. The application is added to the Enterprise Applications list.
  6. Save your configuration.
  7. Stop and restart the server. Before restarting the server ensure that the default queue manager, and the MQ Broker, are running.
Part 6: Run the sample
The sample client program can take up to three arguments:
JMSpsSampleClient [-verbose] [-topic topicname] -msg "MessageText"
The -verbose parameter is optional and causes the client to report its progress. The -topic parameter is also optional. This sample has three pre-defined topics defined for its use: By specifying the topic, the client program controls where to publish the message. If omitted the default topic is news.

The -msg parameter is required. For example:

JMSpsSampleClient -verbose -topic news -msg "Message to be published under the news topic"
The RunPSClient batch file is supplied to simplify running this sample. RunPSClient takes a single argument, the message text. For example:
RunPSClient "Message to be published under the news topic"
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/PubSub.
  2. Edit the RunPSClient 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. Start the message broker if it is not already active. For more information about starting the broker, see Part 3. If the broker is not active the sample cannot complete successfully.
  3. At a command prompt, enter the following command to invoke the sample:

  4. Note: Before starting, modify your java.library.path as you did before running JMSAdmin. See Part 2, step 5.
    RunPSClient "Message to be published under the news topic"
The JMS client publishes the message to the "news" topic as described above, and reports its progress.  Ensure there are no error messages displayed from the client.  Also, check the application server's Standard output and Standard error files to ensure there are no error messages generated from the server.

Successfully executing this sample will result in messages similar to:

Client:
.
Usage  RunPSClient "Message Text"
.
Sending message: 'Message to be published under the news topic'
Retrieving a TopicConnectionFactory from JNDI
Retrieving Topic from JNDI
Creating a Connection
Unable to load message catalog - mqji
Created a Connection
Starting the Connection
Creating a Session
Creating a TopicPublisher
Creating a TextMessage
Publish the message to topic://test/news
Message ID is ID:414d5120514d5f737761796e6520202082fe943b12c00100
Closing TopicPublisher
Closing Session
Closing Connection
End of Sample

Application Server's Standard output file:
SystemOut     U Pub/Sub sample message bean onMessage() method called
SystemOut     U onMessage() text received for messageID: ID:414d5120514d5f737761796e6520202082fe943bf2c00000.
SystemOut     U onMessage() text received: Message to be published under the news topic