Introduction

This series of three articles describes how to use IBM® WebSphere® Studio Application Developer (hereafter called Application Developer) and its embedded messaging support to develop and test Java™ Message Service (JMS) applications. The articles assume a basic understanding of enterprise messaging and its possible uses, but no previous experience with JMS is required.

The three articles will cover the following areas:

• Part 1, this article, demonstrates how to develop and test a JMS point-to-point application.
• Part 2 will demonstrate how to develop and test a JMS publish-subscribe (pub-sub) application.
• Part 3 will demonstrate how to develop, deploy, and test a message-driven bean (MDB).

Back to top

Creating a JMS point-to-point application using Application Developer

We will work through the following steps to create the JMS point-to-point application:

1. Creating a new application client project
2. Importing the point-to-point application code skeleton
3. Completing the application code

Creating a new application client project

Before creating the new application client project, switch to the J2EE navigator view in the J2EE perspective. Start creating the new project by selecting File => New => Application Client Project. The Application Client Project Creation wizard will open, as shown in Figure 1. Check that a J2EE 1.3 project is being created and click Next.

You will now see the application client project panel, which requires a project name and details of the enclosing enterprise application project. Enter a project name of PointToPoint and choose to create a new enterprise application project called JMSTutorialsEAR. Then click Finish and Application Developer will create the new project.

Importing the code skeleton

Now you need to import the code skeleton for the point-to-point application. To start, download and unzip the source code that accompanies this article.

To import the code, expand the PointToPoint project, select the AppClientModule folder, and select File => Import. In the resulting File Import wizard, select File system and click Next. In the File System Import wizard shown in Figure 3 below, select Browse and navigate to the directory in which you unzipped the source code. Select the folder part1, check PointToPoint.java, and click Finish. Ignore the compilation error reported by Application Developer - it will be resolved when the code skeleton is completed by adding the necessary JMS code, as described below.

Completing the application code

Having imported the PointToPoint.java file into the project, double-click its entry in the J2EE navigator view to open its editor. With the editor open, you are ready to begin making the changes that will complete the point-to-point application code. The code skeleton gives you an outline of the code, including a try-catch block to process any exceptions, and a series of comments detailing the changes that need to be made.

The first change is to use the context object to look up the QueueConnectionFactory object from the JNDI namespace. The name of the object to be looked up can be a name of your choice, as you will specify it during the configuration of the test environment below. In the code snippet below, a name of QCF is used.

// Lookup the queue connection factory from the initial context. 
final QueueConnectionFactory qcf = (QueueConnectionFactory) context.lookup("QCF");

Next, use the QueueConnectionFactory to establish a new QueueConnection. The QueueConnectionFactory class provides two forms of the createQueueConnection method, one that takes username and password security credentials and one that does not. Covering security is beyond the scope of this article, so the createQueueConnection method that does not take any parameters is used.

// Create a new queue connection from the queue connection factory. 
final QueueConnection conn = qcf.createQueueConnection();

Having created the QueueConnection, start it so that it can be used to process incoming messages.

// Start the connection conn.start();

The QueueConnection should now be used to create a QueueSession object. When a QueueSession object is created, you must specify whether or not the session is to be transaction, and how it should acknowledge any messages that it receives. In this article, the session will not be transacted and the message acknowledgement will be handled automatically by the underlying JMS provider.

// Create a new queue session from the queue 
// connection. The session should not be transacted 
// and should use automatic message acknowledgement. 
final QueueSession session = conn.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);

Before any messages can be sent and received, you must retrieve from JNDI the Queue object that details where messages are sent to and read from. To do this, use the context object in a similar fashion to the lookup of the QueueConnectionFactory. Once again, the name passed into the lookup can be a name of your choice, as you will configure it below.

// Lookup the queue to be used to send and receive 
// messages from the initial context. 
final Queue q = (Queue) context.lookup("Q");

Having looked up the Queue object, you can use it in the creation of a QueueSender object, which will be used to send messages to the queue. The QueueSender object is created from the existing QueueSession object:

// Create a new queue sender using the queue session. 
// The sender should be created to send messages to the queue q. 
final QueueSender sender = session.createSender(q);

With QueueSender created, you are now ready to create and send a message. Like QueueSenders , JMS messages are created using a Session object. In this article, you will create a TextMessage with its message data initialized with some text of your choosing.

// Create a text message using the queue session. 
// Initialize the message's data to a String of your 
// choice. 
final TextMessage sentMessage = session.createTextMessage("My first JMS message.");

// Send the sentMessage object using the queue sender.
sender.send(sentMessage);
			

Having sent the TextMessage to the queue, you now need to read it back again. You can do this by using a QueueReceiver object created in much the same way as the QueueSender was previously.

// Create a new queue receiver using the queue session. 
// The queue receiver should be created to receive 
// messages from the queue q. 
final QueueReceiver receiver = session.createReceiver(q);

You can now use the QueueReceiver object to read a message from the queue. JMS provides three ways in which a message can be read. Making a call to receive() will cause the code to wait until a message is available on the queue. Invoking receive(n) will cause the code the wait for up to n milliseconds for a message to be available. As its name suggests, calling receiveNoWait() will cause the code to return immediately, regardless of whether a message is available on the queue. In this case, since a message has just been sent to the queue, we are sure that one will be available so the receiveNoWait method will be used.

// Use the queue receiver to receive the message that 
// was sent previously. 
final Message receivedMessage = receiver.receiveNoWait();

As a means of proving that a message has been received and that it's the same message that was sent, output the message to System.out.

// Output the received message to System.out 
System.out.println(receivedMessage);

Save the updated source code and you are now ready to test the point-to-point application.

Back to top

Testing a JMS point-to-point application using Application Developer

Testing involves the following two steps:

1. Configuring the Application Developer Test Environment.
2. Running the point-to-point application.

Configuring the Application Developer Test Environment

Before you can run the PointToPoint application, you need to create and configure a test environment.

In the J2EE perspective, switch to the J2EE Hierarchy view. Right-click the Servers entry and select New => Server and Server Configuration to open the Server Creation wizard, as shown in Figure 4 below. Specify Server name as server1 and select a Server type of WebSphere version 5.0 => Test Environment. Click Finish to complete the creation of the test server.

Having created the new test environment server, you must update its configuration to include the JMS objects that are looked up from JNDI by the PointToPoint application code. Double-click server1 in the J2EE Hierarchy to open its editor and switch to the JMS tab to display the WebSphere JMS Provider Options panel.

The first thing to check on this panel is that it is the Server Settings that are being altered. At the top of the panel, verify that Server Settings is expanded and that both Cell Settings and Node Settings are not. You must add a queue to the JMS server to be used by the PointToPoint application to send and receive its messages. In the JMS Server Properties section of the panel, click Add, enter PointToPointQ, and click OK. The only other change you need to make to the configuration of the JMS server properties is to change its initial state from STOP to START. The configuration of the JMS Server should now resemble Figure 5:

Having configured the embedded JMS server, you must now configure the required QueueConnectionFactory and Queue object in the test environment server's JNDI namespace. In the Server Settings section of the WebSphere JMS Provider Options panel, move down to the JMS Connection Factories section, to the WASQueueConnectionFactories entries table and click the Add button on its right-hand side. In the resulting wizard, specify a Name and JNDI name of QCF, and using the drop-down lists, specify the Node and Server Name as localhost and server1 respectively. Check the configuration changes against those illustrated in Figure 6 and click OK.

The final configuration step is to create a JNDI entry for the queue that was configured on the JMS server above. Move down to the WAS Queue entries table in the JMS Destinations section and click the Add button on its right side. In the resulting wizard, specify a Name of PointToPointQ (this value must match that of the queue that was created on the JMS server), and a JNDI Name of Q (this value must match that used to look up the object in the application code). Using the drop-down, list specify a Node of localhost. Check the configuration changes against those illustrated in Figure 7 and click OK.

Save the updated server configuration and start the server by right-clicking its entry in the Servers tab of the Servers view and selecting Start. You are now ready to run the PointToPoint application.

Running the point-to-point application

In order to run the application, you must create and configure a new Launch Configuration, and specify the application client module's main class.

In the J2EE Hierarchy, double-click the PointToPoint entry in the Application Client Modules section and click Edit next to the Main-Class field. Enter PointToPoint in the field and save the changes.

In the J2EE perspective, open the Launch Configuration wizard by selecting Run => Run. In the Launch Configurations list on the left-hand side of the wizard, select WebSphere V5 Application Client and click New. Name this new configuration PointToPoint and using the drop-down list, specify an Enterprise Application of JMSTutorialsEAR. The wizard should now resemble Figure 8.

The final piece of work to be done before the PointToPoint application client can be run is to configure its classpath. Switch to the Classpath tab and click Add External JARs. Navigate to the directory where Embedded MQ is installed (typically C:/Program Files/IBM/WebSphere MQ), and move down into the Java/lib directory. Select both the com.ibm.mq.jar and the com.ibm.mqjms.jar files and click Open. You can now run the PointToPoint application client by clicking the Run button at the foot of the Launch Configuration wizard. The output from the application should look like this:

IBM WebSphere Application Server, Release 5.0
J2EE Application Client Tool
Copyright IBM Corp., 1997-2002
WSCL0012I: Processing command line arguments.
WSCL0001I: Command line, property file, and system property arguments resolved to:
        File to launch          = e:/java/wsad/workspace/JMSTutorialsEAR
        CC Property File        = null
        Client Jar File         = 
        Alternate DD            = null
        BootstrapHost           = winston
        BootstrapPort           = 
        Trace enabled           = false
        Tracefile               = null
        Init only               = false
        Classpath Parameter     = null
        Security Manager        = disable
        Security Manager Class  = Not used. -CCsecurityManager=disable
        Security Manager Policy = Not used. -CCsecurityManager=disable
        Exit VM                 = false
        Soap Connector Port     = null
        Application Parameters  =
WSCL0013I: Initializing the J2EE Application Client Environment.
WSCL0600I: Binding HandleDelegate object.
WSCL0031I: The object was bound successfully.

WSCL0900I: Initializing and starting components.
WSCL0910I: Initializing component: com.ibm.ws.activity.ActivityServiceComponentImpl
WSCL0911I: Component initialized successfully.
WSCL0901I: Component initialization completed successfully.
WSCL0035I: Initialization of the J2EE Application Client Environment has completed.
WSCL0014I: Invoking the Application Client class PointToPoint

JMS Message class: jms_text
  JMSType:         null
  JMSDeliveryMode: 2
  JMSExpiration:   0
  JMSPriority:     4
  JMSMessageID:    ID:414d51205741535f6c6f63616c686f7324b28a3e20000701
  JMSTimestamp:    1049281792014
  JMSCorrelationID:null
  JMSDestination:  queue:///WQ_Q
  JMSReplyTo:      null
  JMSRedelivered:  false
  JMS_IBM_PutDate:20030402
  JMSXAppID:Websphere MQ Client for Java
  JMS_IBM_Format:MQSTR
  JMS_IBM_PutApplType:28
  JMS_IBM_MsgType:8
  JMSXUserID:Andy
  JMS_IBM_PutTime:11095203
  JMSXDeliveryCount:1
My first JMS message
			

Back to top

Conclusion

This article has illustrated the ease with which an application client that uses JMS can be created and tested using Application Developer. Although the article only worked through a simple send and receive of a JMS message, you can use the techniques you have learned here in the development of any JMS point-to-point application, no matter how complex.

Back to top

Download

Name	Size	Download method
PointToPoint.zip	1KB	FTP|HTTP

Information about download methods

About the author

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Creating a JMS point-to-point application using Application Developer
• Testing a JMS point-to-point application using Application Developer
• Conclusion
• Download
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into WebSphere on developerWorks

Cloud computing for developers

Virtual workshop: Learn how to build a cloud infrastructure and develop/deploy cloud-based applications. (6-8 Apr 2010)

Special offers