Chapter 2   Quick Start Tutorial


This chapter provides a quick introduction to JMS client programming in an MQ environment. It consists of a tutorial-style description of procedures used to create, compile, and run a simple HelloWorldMessage example application.

This chapter covers the following procedures:

• setting up your environment

• starting and testing a broker

• developing a simple client application

• compiling and running a client application

For the purpose of this tutorial it is sufficient to run the MQ message server in a default configuration. For instructions on configuring an MQ message server, please refer to the MQ Administrator's Guide.

Setting Up Your Environment

---

A number of environment variables are used when compiling and running a JMS client. This section describes how to set them.

To set MQ-related environment variables

1. If needed, set the IMQ_HOME environment variable (Windows platform only).

   The IMQ_HOME environment variable is used when compiling and running a JMS client. On the Windows platform, the MQ installer sets IMQ_HOME.

   The directories and environment variables that are set up at installation time are listed below.

   The directories and environment variables that are set up at installation time are listed below.

   
   

   
   
   

   Platform	Settings
   Solaris	There is no single installation directory. The IMQ_HOME environment variable is not used.
   Solaris: Sun ONE Application Server, EE	For Sun ONE Application Server, Evaluation Edition (EE): the default installation directory is the Application Server installation directory/imq The IMQ_HOME environment variable is not used by the software, but is used in MQ documentation to refer to the root installation directory
   Windows	The default installation directory is C:\Program Files\Sun Microsystems\Message Queue 3.0\ The IMQ_HOME environment variable is set by the installer to the MQ installation directory
   Linux	The default installation directory is /opt/imq The IMQ_HOME environment variable is not used by the software, but is used in MQ documentation to refer to the root installation directory

2. Set the JAVA_HOME environment variable.

   Set JAVA_HOME to the directory where you installed the J2SE SDK (Java2 Standard Edition Software Development Kit).

3. Change to the directory in which the example applications are located:

   
   

   
   
   

   Platform	Settings
   Solaris	/usr/demo/imq/jms
   Solaris: Sun ONE Application Server, EE	IMQ_HOME/demo/jms
   Windows	IMQ_HOME/demo/jms
   Linux	IMQ_HOME/demo/jms

   In this directory you will find the application used as an example in this chapter.

4. Set the CLASSPATH environment variable.

   Set CLASSPATH to include the current directory, as well as the jar files (jms.jar, imq.jar, jndi.jar) in the IMQ_HOME/lib directory (/usr/share/lib/imq on Solaris). These are required for compiling and running clients.

   
   

   ---

   Note	JDK 1.4 includes the JNDI jar files and the JSSE jar files (needed for secure connections). So you don't have to include these jar files in the CLASSPATH, unless you are using JDK 1.3 or 1.2 for application development.

   ---

   
   

   
   

   
   
   

   Platform	Settings and Details
   Solaris (csh)	% cd /usr/demo/imq/jms % setenv CLASSPATH .:     /usr/share/lib/imq/jms.jar:     /usr/share/lib/imq/imq.jar:     /usr/share/lib/imq/jndi.jar
   Solaris: Sun ONE Application Server, EE	% cd $IMQ_HOME/demo/jms % setenv CLASSPATH .:     $IMQ_HOME/lib/jms.jar:     $IMQ_HOME/lib/imq.jar:     $IMQ_HOME/lib/jndi.jar
   Windows	C:\>cd %IMQ_HOME%\demo\jms C:\Program Files\Sun Microsystems\ Message Queue 3.0\demo> set CLASSPATH=.;     %IMQ_HOME%\lib\jms.jar;     %IMQ_HOME%\lib\imq.jar;     %IMQ_HOME%\lib\jndi.jar
   Linux (csh)	% cd $IMQ_HOME/demo/jms % setenv CLASSPATH .:     $IMQ_HOME/lib/jms.jar:     $IMQ_HOME/lib/imq.jar:     $IMQ_HOME/lib/jndi.jar

Starting and Testing the MQ Message Server

---

This tutorial assumes that you do not have an MQ message server currently running. A message server consists of one or more brokers—the software component that routes and delivers messages.

(If you run the broker as a UNIX startup process or Windows service, then it is already running and you can skip to "To test a broker" below.)

To start a broker

1. In a terminal window, change directory to IMQ_HOME/bin (/usr/bin on Solaris).

2. Run the broker (imqbrokerd) command as described below.

   The -tty option causes all logged messages to be displayed to the terminal console (in addition to the log file).

   
   

   
   
   

   Platform	Startup Command
   Solaris	% usr/bin/imqbrokerd -tty
   Solaris: Sun ONE Application Server, EE	% IMQ_HOME/bin/imqbrokerd -tty
   Windows	C:\Program Files\Sun Microsystems\ Message Queue 3.0\bin> imqbrokerd -tty
   Linux	% IMQ_HOME/bin/imqbrokerd -tty

The broker will start and display a few messages before displaying the message, "imqbroker@host:7676 ready." It is now ready and available for clients to use.

To test a broker

One simple way to check the broker startup is by using the MQ Command (imqcmd) utility to display information about the broker.

1. In a separate terminal window, change directory to IMQ_HOME/bin (/usr/bin on Solaris).

2. Run imqcmd with the arguments shown below.

   
   

   
   
   

   Platform	Settings and Details
   Solaris	% /usr/bin/imqcmd query bkr -u admin -p admin
   Solaris: Sun ONE Application Server, EE	% IMQ_HOME/bin/imqcmd query bkr -u admin -p admin
   Windows	C:\Program Files\Sun Microsystems\ Sun One Message Queue 3.0\bin>     imqcmd query bkr -u admin -p admin
   Linux	% IMQ_HOME/bin/imqcmd query bkr -u admin -p admin

The output displayed should be similar to what is shown below.

Querying the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Auto Create Queues	true
Auto Create Topics	true
Auto Create Queue Delivery Policy	Single
Cluster Broker List (active)	myhost/111.222.333.444:7676 imqbroker
Cluster Broker List (configured)
Cluster Master Broker
Cluster URL
Current Number of Messages in System	0
Current Size of Messages in System	0
Instance Name	imqbroker
Log Level	INFO
Log Rollover Interval (seconds)	604800
Log Rollover Size (bytes)	0 (unlimited)
Max Message Size (bytes)	70m
Max Number of Messages in System	0 (unlimited)
Max Size of Messages in System	0 (unlimited)
Primary Port	7676
Version	3.0
Successfully queried the broker.

Developing a Simple Client Application

---

This section leads you through the steps used to create a simple "Hello World" application that sends a message to a queue destination and then retrieves the same message from the queue. You can find this HelloWorldMessage application at IMQ_HOME/demo/jms (/usr/demo/imq/jms on Solaris).

The following steps highlight Java programming language code that you use to set up a client to send and receive messages:

To program the HelloWorldMessage example application

1. Import the interfaces and MQ implementation classes for the JMS API.

   The javax.jms package defines all the JMS interfaces necessary to develop a JMS client.

   import javax.jms.*;

2. Instantiate an MQ QueueConnectionFactory administered object.

   A QueueConnectionFactory object encapsulates all the MQ-specific configuration properties for creating QueueConnection connections to an MQ message server.

   QueueConnectionFactory myQConnFactory =
      new com.sun.messaging.QueueConnectionFactory();

   ConnectionFactory administered objects can also be accessed through a JNDI lookup (see "Looking Up ConnectionFactory Objects"). This approach makes the client code JMS-provider independent and also allows for a centrally administered messaging system.

3. Create a connection to the MQ message server.

   A QueueConnection object is the active connection to the MQ message server in the Point-To-Point programming domain.

   QueueConnection myQConn =
      myQConnFactory.createQueueConnection();

4. Create a session within the connection.

   A QueueSession object is a single-threaded context for producing and consuming messages. It enables clients to create producers and consumers of messages for a queue destination.

   QueueSession myQSess = myQConn.createQueueSession(false,
      Session.AUTO_ACKNOWLEDGE);

   The myQSess object created above is non-transacted and automatically acknowledges messages upon consumption by a consumer.

5. Instantiate an MQ queue administered object corresponding to a queue destination in the MQ message server.

   Destination administered objects encapsulate provider-specific destination naming syntax and behavior. The code below instantiates a queue administered object for a physical queue destination named "world".

   Queue myQueue = new.com.sun.messaging.Queue("world");

   Destination administered objects can also be accessed through a JNDI lookup (see "Looking Up Destination Objects"). This approach makes the client code JMS-provider independent and also allows for a centrally administered messaging system.

6. Create a QueueSender message producer.

   This message producer, associated with myQueue, is used to send messages to the queue destination named "world".

   QueueSender myQueueSender = myQSess.createSender(myQueue);

7. Create and send a message to the queue.

   You create a TextMessage object using the QueueSession object and populate it with a string representing the data of the message. Then you use the QueueSender object to send the message to the "world" queue destination.

   TextMessage myTextMsg = myQSess.createTextMessage();
   myTextMsg.setText("Hello World");
   System.out.println("Sending Message: " + myTextMsg.getText());
   myQueueSender.send(myTextMsg);

8. Create a QueueReceiver message consumer.

   This message consumer, associated with myQueue, is used to receive messages from the queue destination named "world".

   QueueReceiver myQueueReceiver =
      myQSess.createReceiver(myQueue);

9. Start the QueueConnection you created in Step 3.

   Messages for consumption by a client can only be delivered over a connection that has been started (while messages produced by a client can be delivered to a destination without starting a connection, as in Step 7.

   myQConn.start();

10. Receive a message from the queue.

    You receive a message from the "world" queue destination using the QueueReceiver object. The code, below, is an example of a synchronous consumption of messages (see "Message Consumption: Synchronous and Asynchronous"). For samples of asynchronous consumption see Table 2-1.

    Message msg = myQueueReceiver.receive();

11. Retrieve the contents of the message.

    Once the message is received successfully, its contents can be retrieved.

    if (msg instanceof TextMessage) {
       TextMessage txtMsg = (TextMessage) msg;
       System.out.println("Read Message: " + txtMsg.getText());
    }

12. Close the session and connection resources.

    myQSess.close();
    myQConn.close();

Compiling and Running a Client Application

---

To compile and run JMS clients in an MQ environment, it is recommended that you use the Java2 SDK Standard Edition v1.4, though versions 1.3 and 1.2 are also supported. The recommended SDK can be downloaded from the following location:

http://java.sun.com/j2se/1.4

Be sure that you have set the CLASSPATH environment variable to point to the jms.jar and imq.jar files, as described in Step 4, before attempting to compile or run a client application.

The following instructions are based on the HelloWorldMessage application created in "Developing a Simple Client Application", and also located in the MQ 3.0 example applications directory:

IMQ_HOME/demo/jms (/usr/demo/imq/jms on Solaris)

To compile and run the HelloWorldMessage application

1. Make the directory containing the application your current directory.

   The MQ 3.0 example applications directory on Solaris is not writable by users, so copy the HelloWrodMessage application to a writable directory and make that directory your current directory.

2. Compile the HelloWorldMessage application as shown below.

   
   

   
   
   

   Platform	Settings and Details
   On Solaris (csh)	% $JAVA_HOME/bin/javac HelloWorldMessage.java
   On Windows	C:\Program Files\Sun Microsystems\Message Queue 3.0\ demo\jms>%JAVA_HOME%\bin\javac HelloWorldMessage.java
   On Linux (csh)	% $JAVA_HOME/bin/javac HelloWorldMessage.java

   This step above results in the HelloWorldMessage.class file being created in the current directory.

3. Run the HelloWorldMessage application as shown below.

   The output shown is what displays when you run the HelloWorldMessage example in the examples/jms directory.

   
   

   
   
   

   Platform	Settings and Details
   On Solaris (csh)	% $JAVA_HOME\bin\java HelloWorldMessage
   On Windows	C:\Program Files\Sun Microsystems\Message Queue 3.0\ \demo\jms> %JAVA_HOME%\bin\java HelloWorldMessage
   On Linux (csh)	% $JAVA_HOME\bin\java HelloWorldMessage

   The output displayed when you run the HelloWorldMessage is as follows:

   Sending Message: Hello World

   Read Message: Hello World

Example Application Code

---

The example applications provided by MQ 3.0 consist of both JMS messaging applications as well as JAXM messaging examples (see "Working With SOAP Messages" for more information).

JMS Examples

A listing of the code in the HelloWorldMessage tutorial example can be found, along with code from a number of other example applications, at the following location:

IMQ_HOME/demo/jms (/usr/demo/imq/jms on Solaris)

The directory includes a README file that describes each example application and how to run it. The examples include standard JMS sample programs as well as MQ-supplied example applications. They are summarized in the following two tables.

Table 2-1 is a listing and brief description of the JMS sample programs.

Table 2-1    JMS Sample Programs 

Name of Example Application	Description
SenderToQueue	Sends a text message using a queue.
SynchQueueReceiver	Synchronously receives a text message using a queue.
SynchTopicExample	Publishes and synchronously receives a text message using a topic.
AsynchQueueReceiver	Asynchronously receives a number of text messages using a message listener.
AsynchTopicExample	Publishes five text messages to a topic and asynchronously gets them using a message listener.
MessageFormats	Writes and reads messages in five supported message formats.
MessageConversion	Shows that for some message formats, you can write a message using one data type and read it using another.
ObjectMessages	Shows that objects are copied into messages, not passed by reference.
BytesMessages	Shows how to write, then read, a Bytes Message of indeterminate length.
MessageHeadersTopic	Illustrates the use of the JMS message header fields.
TopicSelectors	Shows how to use message properties as message selectors.
DurableSubscriberExample	Shows how you can create a durable subscriber that retains messages published to a topic while the subscriber is inactive.
AckEquivExample	Shows how to ensure that a message will not be acknowledged until processing is complete.
TransactedExample	Demonstrates the use of transactions in a simulated e-commerce application.
RequestReplyQueue	Demonstrates use of the JMS request/reply facility.

Table 2-2 is a listing and brief description of the MQ-supplied example applications.

Table 2-2    MQ-supplied Example Applications 

Name of Example Application	Description
HelloWorldMessage	Sends and receives a "Hello World" message.
XMLMessageExample	Reads an XML document from a file, sends it to a queue, processes the message from the queue as an XML document, and converts it to a DOM object.
SimpleChat	Illustrates how MQ can be used to create a simple GUI chat application.
SimpleJNDIClient	Illustrates how a client would use JNDI lookups to access administered objects created by an administrator and placed in an object store (see the Administration Console tutorial in the MQ Administrator's Guide).

JAXM Examples

A number of examples illustrating how to send and receive SOAP messages are provided at the following location:

IMQ_HOME/demo/jaxm (/usr/demo/imq/jaxm on Solaris)

The directory includes a README file that describes each example application and how to run it. These example applications are summarized in Table 2-3.

Table 2-3    SOAP Messaging Example Applications

Name of Example Application	Description
SendSOAPMessage	A standalone client that sends a SOAP message.
SOAPEchoServlet	A servlet that echoes a SOAP message.
SendSOAPMessageWithJMS	A standalone client that constructs a SOAP message, wraps it as a JMS message, and then publishes this message to a topic.
ReceiveSOAPMessageWithJMS	A JMS message listener that subscribes to a topic where it receives a JMS-wrapped SOAP message, which it then converts to a SOAP message.
SOAPtoJMSServlet	A servlet that receives a SOAP message, wraps it as a JMS message and publishes it to a topic.