Sun ONE Message Queue 3.5 Java Client Developer's Guide |
Chapter 2
Quick Start TutorialThis chapter provides a quick introduction to JMS client programming in a Sun ONE Message Queue (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 topics:
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.
The minimum JDK level required to compile and run MQ clients is 1.2.2.
Setting Up Your EnvironmentYou need to set the CLASSPATH enivronment variable when compiling and running a JMS client. (The IMQ_HOME variable, where used, refers to the directory where MQ is installed on Windows platforms and some Sun ONE Application Server platforms.)
The value of CLASSPATH depends on the following factors:
Table 2-1 specifies the directories where jar files are to be found on the different platforms:
Table 2-1 jar File Locations
Platform
Directory
Solaris
/usr/share/lib/
Solaris:
Sun ONE Application Server, Evaluation EditionIMQ_HOME/lib/
Linux
/opt/imq/lib/
Windows
IMQ_HOME\lib\
Table 2-2 lists the jar files you need to compile and run different kinds of code.
A client application must be able to access JNDI jar files (jndi.jar) even if the application does not use JNDI directly to look up MQ administered objects. This is because JNDI is referenced by methods belonging to the Destination and ConnectionFactory classes.
JNDI jar files are bundled with JDK 1.4. Thus, if you are using this JDK, you do not have to add jndi.jar to your CLASSPATH setting. However, if you are using an earlier version of the JDK, you must include jndi.jar in your classpath.
If you are using JNDI to look up MQ administered objects, you must also include the following files in your CLASSPATH setting:
Starting and Testing the MQ Message ServerThis 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
- In a terminal window, change to the directory containing MQ executables:
Table 2-3 Location of MQ Executables
Platform
Location
Solaris
/usr/bin/
Linux
/opt/imq/bin/
Windows
IMQ_HOME/bin/
- Run the broker startup command (imqbrokerd) as shown below.
imqbrokerd -tty
The -tty option causes all logged messages to be displayed to the terminal console (in addition to the log file).
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.
- In a separate terminal window, change to the directory containing MQ executables (see Table 2-3).
- Run imqcmd with the arguments shown below.
imqcmd query bkr -u admin -p admin
The output displayed should be similar to what is shown below.
Developing a Simple Client ApplicationThis section leads you through the steps used to create a simple “Hello World” client application that sends a message to a queue destination and then retrieves the same message from the queue. You can find this example, named HelloWorldMessage in the IMQ_HOME/demo/helloworld/helloworldmessage dirctory.
The following steps describe the HelloWorldMessage example
- 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.*;
- 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.
- 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();- 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.
- 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.
- 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);
- 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);- 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);- 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();
- 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").
Message msg = myQueueReceiver.receive();
- 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());
}- Close the session and connection resources.
myQSess.close();
myQConn.close();
Compiling and Running a Client ApplicationTo compile and run Java 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:
Be sure that you have set the CLASSPATH environment variable correctly, as described in "Setting Up Your Environment", before attempting to compile or run a client application.
The following instructions are based on the HelloWorldMessage application, as created in "Developing a Simple Client Application", and located in the MQ 3.5 JMS example applications directory (see Table 2-4). Please note that these instructions are furnished as an example. You do not actually need to compile the example; it is shipped precompiled. Of course, if you modify the source for the example, you will need to recompile.
To Compile and Run the HelloWorldMessage Application
- Make the directory containing the application your current directory.
The MQ 3.5 example applications directory on Solaris is not writable by users, so copy the HelloWorldMessage application to a writable directory and make that directory your current directory.
- Compile the HelloWorldMessage application as shown below.
javac HelloWorldMessage.java
This step results in the HelloWorldMessage.class file being created in the current directory.
- Run the HelloWorldMessage application:
java HelloWorldMessage
The following output is displayed when you run HelloWorldMessage.
Sending Message: Hello World
Read Message: Hello World
Example Application CodeThe example applications provided by MQ 3.5 consist of both JMS messaging applications as well as JAXM messaging examples (see "Working With SOAP Messages" for more information).
Directories containing example application code are set as follows:
Each directory (except for the JMS directory) contains a README file that describes the source files included in that directory. Table 2-4 lists and describes the contents of the directories of interest to MQ Java clients.
Table 2-4 Example Programs
Directory
Contents
helloworld
Simple programs that show how a JMS client is created and deployed in MQ. These examples also include the steps required to create administered objects in MQ, as well ashow to use JNDI in the client to look up and use those objects.
jms
Sample programs that demonstrate the use of the JMS API with MQ.
jaxm
Sample programs that demonstrate how to use SOAP messages in conjunction with JMS in MQ.
applications
Two directories
monitoring
Sample programs that demonstrate how to use the JMS API for monitoring the broker.
jdbc
Examples for plugging in a PointBase and an Oracle database.
imqobjmgr
Examples of imqobjmgr command files.