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:
-
WebSphere Application Server Advanced Edition (AE) or Advanced Developer
Edition (AEd).
-
WebSphere Application Server Enterprise Edition (EE) Extended messaging
support.
-
MQSeries Server (Version 5.2 or higher)
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:
-
Open a command window and change to the directory where the MQJMS_PSQ.mqsc
file is installed (for example, mq_install_dir/java/bin).
-
Enter the following command:
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:
-
A TopicConnectionFactory (TCF) and three topics used by the Java JMS client
application.
-
A TopicConnectionFactory (wstcf) used by the Listener and a generic topic
to subscribe to all of the client topics.
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:
-
In the command window, change to the JMS directory (for example, /mq_install_dir/java/bin).
-
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:
-
AE:
-
Locate the line specifying the INITIAL_CONTEXT_FACTORY and ensure that
its value is set to:
com.ibm.ejs.ns.jndi.CNInitialContextFactory
-
Locate the line specifying the PROVIDER_URL and ensure that its value is
set to:
iiop://localhost/
-
AEd:
-
Locate the line specifying the INITIAL_CONTEXT_FACTORY and ensure that
the value is set to:
com.sun.jndi.fscontext.RefFSContextFactory
-
Locate the line specifying the PROVIDER_URL and ensure that the value is
set to:
file:/directory_path
Be sure the line is uncommented while all others are commented out.
The directory_path is the location of the external naming information.
You must create this directory and update the information on the PROVIDER_URL
line with the fully qualified directory path name.
Ensure that the directory named here exists.
-
Save the JMSAdmin.config file.
-
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:
-
Prepend the following path onto the Java call:
WAS_HOME/java/jre/bin
-
Provide the following directive to the Java run time as an option:
-Djava.ext.dirs=WAS_HOME\java\lib;
WAS_HOME\java\jre\lib\ext;
WAS_HOME\lib;
WAS_HOME\java\lib
-
UNIX:
-Djava.ext.dirs=/WAS_HOME/java/lib:
/WAS_HOME/java/jre/lib/ext:
/WAS_HOME/lib:
/mqm_install_dir/java/lib
-
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:
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)
-
Ensure your WebSphere Server has been started, then enter the following
command to run the supplied script:
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.
-
Starting the broker
At a command prompt enter the following command:
strmqbrk
The broker starts and the following message is displayed:
MQSeries message broker started for queue manager QM_servername.
Displaying broker status
At a command prompt enter the following command:
dspmqbrk
If the broker is active, it responds with the following message:
MQSeries message broker for queue manager QM_servername running.
Stopping the broker
At a command prompt enter the following command:
endmqbrk
This causes the broker to terminate. The following message is displayed:
MQSeries message broker for queue manager QM_servername ended.
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.
-
Open a command window and change to the WAS_HOME/bin directory.
-
Start the administrative server.
-
Start the administrative console. If the server is active, stop and restart
it as follows:
-
Stopping the server:
Use the administrative console to bring down all application servers,
then stop the administrative server.
-
Starting the server:
-
Windows: select Start > Programs > IBM WebSphere > Application Server
V4.0 AE > Start Admin Server
-
UNIX:
-
Open a command window and change to the WAS_HOME/bin directory
-
Enter the following commands to start the administrative server:
Note: Before starting, modify your java.library.path as you
did before running JMSAdmin. See Part 2, step 5.
-
Manually enable the Extended Messaging service as follows:
-
In the administrative console, expand Nodes > your_node.
-
Right click on Application Servers and select New. Create
a new application server called PubSub. Click OK, then
click Apply.
-
Your server should appear under the Application Server, select it, then
select the Custom tab.
-
Select Extended Messaging Support Service and click Edit.
-
Enter the following Configuration File URL:
WAS_HOME/Enterprise/samples/messaging/src/PubSub/jmsconfigPS.xml
-
Specify a classpath of
<mq_install_dir>/java/lib/com.ibm.mq.jar:<mq_install_dir>/java/lib/com.ibm.mqjms.jar
Note: on Windows platforms, the separator is a semicolon (;)
not a colon (:)
-
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 jmsconfigPS.xml file. This file would contain
the definitions from both sample configuration files.
Part 4b: Enable Extended Messaging support on the server (AEd)
Complete the following steps to enable Extended Messaging support on
AEd:
-
Open a command window and change to the WAS_HOME/bin directory.
-
Start the administrative server. If the server is active, stop and restart
it as follows:
Note: Before starting, modify your java.library.path as you
did before running JMSAdmin. See Part 2, step 5.
-
Stopping the server:
-
Windows: stopserver
-
UNIX: ./stopServer.sh
-
Starting the server:
-
Open a command window and change to the WAS_HOME/bin directory
-
Enter one of the following commands to start the administrative server:
Note: Before starting, modify your java.library.path as you
did before running JMSAdmin. See Part 2, step 5.
-
Windows: startserver.bat
-
UNIX: ./startServer.sh
-
Start the administrative console by entering the following URL in your
Web browser:
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.
-
Click OK, and then save your changes to the provider.
-
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.
-
Select JMS Connection Factories and click New. Specify the
following values:
Name: ConnectionFactory1
JNDI Name: Sample/JMS/TCF
External JNDI Name: Sample/JMS/TCF
Connection Type: Topic
Click OK
-
Click New again and specify the following values:
Name: ConnectionFactory2
JNDI Name: Sample/JMS/TCFBean
External JNDI Name: Sample/JMS/TCFBean
Connection Type: Topic
Click OK
-
Select JMS Destinations and click New. Specify the following
values:
Name: T1
JNDI Name: Sample/JMS/listen
External JNDI Name: Sample/JMS/listen
Destination Type: Topic
Click OK
-
Click New again and specify the following values:
Name: T2
JNDI Name: Sample/JMS/news
External JNDI Name: Sample/JMS/news
Destination Type: Topic
Click OK
-
Click New again and specify the following values:
Name: T3
JNDI Name: Sample/JMS/sport
External JNDI Name: Sample/JMS/sport
Destination Type: Topic
Click OK
-
Click New again and specify the following values:
Name: T4
JNDI Name: Sample/JMS/weather
External JNDI Name: Sample/JMS/weather
Destination Type: Topic
Click OK
-
Manually enable the Extended Messaging Service as follows
-
From the administrative console, expand the Nodes > your_node and
Applications
Servers > Default Server. Click Custom Services.
-
Select Extended Messaging Support Service.
-
In theExternal Config URL field, type the following path:
WAS_HOME/Enterprise/samples/messaging/src/PubSub/jmsconfigPS.xml
-
Specify a classpath of
<mq_install_dir>/java/lib/com.ibm.mq.jar:<mq_install_dir>/java/lib/com.ibm.mqjms.jar
-
Click OK.
-
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.
-
In the administrative console, select Wizards > Install Enterprise Application.
-
Select your node and select the Install Application (*.ear)
-
Click Browse and open the following file:
WAS_HOME/Enterprise/samples/messaging/src/PubSub/JMSPSSampleEJB.ear
-
Click Next on each of the subsequent panels until you reach the
Selecting
the Application Server panel.
-
Click Select Server. Select the server you created (PubSub)and
click OK.
-
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.
-
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:
-
In the administrative console, select Nodes > your_node > Enterprise
Applications.
-
Click Install.
-
Click Browse, and open the following file:
WAS_HOME/Enterprise/samples/messaging/src/PubSub/JMSPSSampleEJB.ear
-
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.
-
Save your configuration.
-
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:
-
Change directory to WAS_HOME/Enterprise/samples/messaging/src/PubSub.
-
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:
-
Change the value of the MQ_LIB variable to point to the correct
path.
-
Prepend the following path onto the Java call:
WAS_HOME/java/jre/bin
-
As an option to the Java run time, provide the following directive (on
Windows, use a semi-colon instead of a colon):
-Djava.ext.dirs=/WAS_HOME/lib:/mqm_install_dir/java/lib:/WAS_HOME/java/jre/lib/ext
To run the sample, perform the following steps:
-
Start the Server. If is already started, stop the server and restart
it.
-
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.
-
At a command prompt, enter the following command to invoke the sample:
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