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:
-
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 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:
-
Open a command window, and enter the following command to start the default
queue manager (if not already started):
strmqm
-
Enter the following command to start the utility (You should see a message,
"Starting MQSeries Commands." Note: There is no command prompt.):
runmqsc
-
Define Q1 by entering the following command:
define Qlocal(Q1) put(enabled) get(enabled)
-
Define Q2 by entering the following command:
define Qlocal(Q2) put(enabled) get(enabled)
-
Use the following command to view and verify your queue definitions:
display Qlocal(Q*)
-
Enter the following command to exit the utility:
end
Part 2: Define JNDI resources
A sample configuration file (JMSppSetup.scp) defines the JNDI resources.
Those resources are:
-
A QueueConnectionFactory (QCF)
-
Two queues (Q1 and Q2)
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:
-
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.
The following are examples for different operating systems:
Win2k/NT - PROVIDER_URL=file:///C:/JNDI-Directory
UNIX - PROVIDER_URL=file:////tmp/JNDI
-
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 (where WAS_HOME is
the location of your WebSphere/AppServer installation):
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;
mqm_install_dir\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. Run the
following 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)
-
Enter the following command to run the supplied script:
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.
-
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:
-
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.
-
Start the administrative console.
-
In the administrative console, select Resources > JMS Providers.
-
Right click on JMS Providers and select New.
-
On the General Property tab, specify the following:
Name: MQProvider
Context Factory: com.ibm.websphere.naming.WsnInitialContextFactory
Provider URL:iiop://localhost/
-
On the Nodes tab, specify the following:
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
-
Expand the JMS provider (MQProvider) that you just created and add your
Connection Factory and Destinations.
-
Select JMS Connection Factories and click New. Specify the
following values:
Name: ConnectionFactory
External JNDI path: Sample/JMS/QCF
Select OK
-
Select JMS Destinations and click New. Specify the following
values:
Name: Q1
External JNDI path: Sample/JMS/Q1
Select OK
-
Click New again and specify the following values:
Name: Q2
External JNDI path: Sample/JMS/Q2
Select OK
-
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 PtoPSrv. Click OK.
-
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/PtoP/jmsconfig.xml
-
Specify a classpath of
<mq_install_dir>/java/lib/com.ibm.mq.jar:<mq_install_dir>/java/lib/com.ibm.mqjms.jar
-
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:
-
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:
-
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.
-
Select JMS Connection Factories and click New. Specify the
following values:
Name: ConnectionFactory
JNDI Name: Sample/JMS/QCF
External JNDI Name: Sample/JMS/QCF (Sample\JMS\QCF
on Windows systems)
Connection Type: Queue
Click OK
-
Select JMS Destinations and click New. Specify the following
values:
Name: Q1
JNDI Name: Sample/JMS/Q1
External JNDI Name: Sample/JMS/Q1 (Sample\JMS\Q1
on Windows systems)
Destination Type: Queue
Click OK
-
Click New again and specify the following values:
Name: Q2
JNDI Name: Sample/JMS/Q2
External JNDI Name: Sample/JMS/Q2 (Sample\JMS\Q2
on Windows systems)
Destination Type: Queue
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/PtoP/jmsconfig.xml
-
Specify a classpath of
<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)
-
Click OK.
-
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.
-
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/PtoP/JMSPPSampleEJB.ear
-
Click Next on each of the subsequent panels until you reach the
Mapping
Resource References to Resources panel.
-
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.
-
Click Next until you arrive at the Selecting the Application
Server panel.
-
Click Select Server. Select the server you created (PtoPSrv)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 PtoPSrv
application server.
Part 4b: 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/PtoP/JMSPPSampleEJB.ear
-
Continue to click Next until you reach the Mapping Resource References
to JNDI Names panel.
-
For jms/SamplePPQCF, enter Sample/JMS/QCF.
-
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.
-
Save your configuration.
-
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:
-
Change directory to WAS_HOME/Enterprise/samples/messaging/src/PtoP.
-
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:
-
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.
-
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.
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.