Testing WebSphere JMS applications when disconnected from WebSphere MQ

This article shows you how to locally test a JMS application running on WebSphere Application Server without having to connect to a WebSphere MQ queue manager, by configuring your local WebSphere Test Environment to simulate WebSphere MQ. This configuration enables you to identify and resolve defects earlier in the development life cycle, without having to either install a local queue manager or wait for access to a remote queue manager.

Annette C. Green (greenac@us.ibm.com), Senior I/T Specialist, IBM

Annette Green works as a Senior I/T Specialist for IBM Global Business Services in the Washington, D.C. area. She has 15 years of experience in enterprise application design and development, and system integration. Annette is an IBM-certified MQ developer, a Sun-certified Java programmer, and the creator of two WebSphere MQ SupportPacs: MA0J and MA92. You can contact Annette at greenac@us.ibm.com.



28 March 2012

Also available in Chinese

Introduction

When testing JMS applications developed for WebSphere Application Server, the development team may not always have access to a WebSphere MQ environment. As a result, you may not be able to troubleshoot and identify defects until the application code has been deployed into an integrated environment. This article shows you how to configure your local WebSphere Test Environment to simulate a WebSphere MQ queue manager and its associated queues, so that you can identify and resolve defects earlier in the development life cycle.

In order to simulate an environment that resembles WebSphere MQ, you will be taking advantage of the WebSphere Application Server default messaging provider for V5, which uses an internal service integration bus (SIBus) that itself contains a messaging engine and associated queues. As a result, instead of defining Java Message Service (JMS) resources to access WebSphere MQ queues, you will define JMS resources to access queue destinations on the SIBus. This article shows you how to define these resources, and includes a sample application that demonstrates placing and retrieving messages to and from the defined queues.

These instructions assume that the local test environment for WebSphere Application Server V6 or later has been installed in your development environment. For users of WebSphere Application Server V7, the Java Software Development Kit (SDK) must be at least at V1.6.0 Java Technology Edition SR9 FP1 for WebSphere Application Server, or at the latest Java SDK version for WebSphere Application Server V7.

The sample application

The sample application uses the resources shown in Table 1 below. This article walks you through defining each of these resources, and shows you how to customize these instructions for your specific application. For the sample application, you will define two queues under the WebSphere Application Server V5 messaging provider. The first queue, called IncomingQueue, is designated for incoming messages that are processed by the application. The second queue, called OutgoingQueue, stores messages sent by the sample application. These two internal queues simulate their corresponding WebSphere MQ queues and, for each of these queues, you will define corresponding JMS queues and queue connection factories (QCFs).

The sample application has a message-driven enterprise Java bean (EJB) called IncomingMessageReceiverBean. It listens for messages via the IncomingListenerPort listener port and it receives messages placed on the IncomingQueue queue. The application uses a stateless session EJB called OutgoingMessageSenderBean to send messages to the OutgoingQueue queue.

Table 1. Resources used by the sample application
WebSphere queue nameJMS queueJMS QCFListener portEJB name
IncomingQueuejms/IncomingQueuejms/IncomingQCFIncomingListenerPortIncomingMessageReceiverBean
OutgoingQueuejms/OutgoingQueuejms/OutgoingQCF---OutgoingMessageSenderBean

When configuring the local WebSphere Test Environment for your particular application, use the same Java Naming and Directory Interface (JNDI) names that are defined in your integrated WebSphere environment.

Creating JMS queue destination

For any JMS application running on WebSphere Application Server, the normal configuration process includes defining JMS queues for your specific messaging provider (such as WebSphere MQ). For this scenario, you will define queue destinations for the WebSphere V5 messaging provider. Using Rational Application Developer (or an equivalent integrated development environment), start up the WebSphere test server and perform the following steps:

  1. Log into the Administrative Console and go to Resources => JMS Providers => V5 default messaging provider (Use Server scope).
  2. Under the Additional Properties heading, click WebSphere queue destinations or Queues, depending on your WebSphere version
  3. Click New to create a new queue destination for each of the JMS resources shown in Table 2 below. Note the queue name, since you will use this value later when creating queues on the SIBus.
Table 2. WebSphere queue destination values
Queue NameQueue JNDI name
IncomingQueuejms/IncomingQueue
OutgoingQueuejms/OutgoingQueue

When creating JMS queue destinations for your specific application, the JNDI names should match the names defined in your integrated environment under Resources => JMS Providers => WebSphere MQ => WebSphere MQ queue destinations, which is where the base queue name and associated queue manager name are specified.

  1. Click OK to save locally and then save changes to the master configuration.

Creating JMS queue connection factories

For each JMS queue used by a JMS application, a corresponding JMS QCF is also required. For this configuration, you will create QCFs under the WebSphere V5 default messaging provider. Perform the following steps on your test server:

  1. In the Administrative Console, go to Resources => JMS Providers => V5 default messaging.
  2. Under the Additional Properties heading, click WebSphere queue connection factories or Queue connection factories, depending upon your version.
  3. Click New to create a new QCF for each resource shown in Table 3 below:
Table 3. WebSphere Queue Connection Factory values
QCF NameQCF JNDI Name
IncomingQCFjms/IncomingQCF
OutgoingQCFjms/OutgoingQCF

When creating the JMS QCFs for your specific application, the JNDI names should match the names defined in your integrated environment under Resources => JMS Providers => WebSphere MQ => WebSphere MQ queue connection factories, which is where the queue manager and channel detail are specified.

  1. Click OK to save locally and then save changes to the master configuration.

Defining port settings for the JMS server

This section shows you how to update settings associated with the JMS provider of your local server:

  1. In the administrative console, go to Servers => (WebSphere) Application Servers => <serverName>.
  2. Under the Communications heading, click the Ports link. Take note of the port value for the MQ transport port named SIB_MQ_ENDPOINT_ADDRESS.
  3. Click New to create a new port and select JMSSERVER_QUEUED_ADDRESS from the Well-known port field. Enter the hostname of your test server for the Host field and enter the port number used by SIB_MQ_ENDPOINT_ADDRESS in the Port field.
  4. Click OK to save locally and then save changes to the master configuration

Creating a service integration bus

Service integration technology is integrated into WebSphere Application Server to accommodate asynchronous messaging services. The default messaging providers for WebSphere Application Server use this service integration technology. In this step, you will define an SIBus and then join the application server to the bus as a bus member, which causes WebSphere Application Server to automatically create a messaging engine for it. The application server uses the messaging engine for sending and receiving messages to destinations on the bus. You can also use an existing SIBus, if available, rather create a new one.

  1. From the Administrative Console, go to Service integration => Buses.
  2. Click New to create a new SIBus
  3. Enter a name for the bus, deselect the Secure checkbox, and then click Apply or Finish.
  4. Under the Topology heading of your new bus, click Bus members.
  5. Click Add to add the application server as a bus member.
  6. Select the Server radio button, select <nodeName : serverName>, and keep the Default field for the data store.
  7. Click Next and then Finish.
  8. Click OK to save locally and then save changes to the master configuration. A messaging engine has been created for your server under Service integration=> Buses => <busName> => Messaging engines.

Creating the internal queue manager

In the previous steps you configured the JMS resources used by the sample application. However, since you are using the V5 default messaging provider, you will also need to create an association between these JMS resources and their corresponding queue destinations on the SIBus. Because the V5 default messaging provider uses WebSphere MQ client protocols, this association is called the WebSphere MQ client link. It provides the bridge for any JMS application to communicate with the V5 JMS resources and the messaging engine on the SIBus, as shown in Figure 1 below. As a result, the WebSphere MQ client link acts as an internal queue manager and enables access to destinations on the SIBus.

Figure 1. Connectivity between messaging engine and JMS application
Connectivity between messaging engine and JMS application

Follow the steps below to create and configure the WebSphere MQ client link:

  1. From the Administrative Console, go to Service Integration => Buses => <busName>.
  2. Under the Topology heading, click Messaging Engines.
  3. Click on the <nodeName>.<serverName>-<busName> link.
  4. Under the Additional Properties heading, click WebSphere MQ client links.
  5. From the next screen, click New to create a new WebSphere MQ client link with the values shown in Table 4 below:
Table 4. WebSphere MQ client link values
Field nameField valueComments
NameDefault.MQClientLinkUse any value for this field
MQ Channel NameWAS.JMS.SVRCONNChannel name configured for V5
Queue Manager NameWAS_<nodeName>_<serverName>The correct value is initially displayed by default
Default queue managerChecked
  1. Click OK to save locally and then save changes to the master configuration.

Creating queue destinations on the service integration bus

For each JMS queue defined for the WebSphere V5 messaging provider, you will need to create a corresponding destination on your SIBus. This section shows you how to create a queue destination on your SIBus and then assign it to the application server bus member:

  1. From the Administrative Console, go to Service Integration => Buses => <busName>.
  2. Under the Destination Resources heading, click Destinations.
  3. On the next screen, select New to create a bus destination for each row in Table 5 below. The following steps walk you through each screen.
Table 5. Queue Bus destination values
Destination typeIdentifierBus member
QueueIncomingQueue<nodeName>:<serverName>
QueueOutgoingQueue<nodeName>:<serverName>
  1. On the Create new destination screen, select the Queue destination type.
  2. On the Set queue attributes screen, enter the queue name from Table 5 above. This value is the same as the queue name used for the WebSphere V5 messaging provider JMS queue (see Table 2 above). For your specific JMS application, the name of your WebSphere V5 JMS queue should match the name used for its corresponding bus queue.
  3. On the Assign the queue to a bus member screen, select the bus member name <nodeName>:<serverName>. The bus member represents your application server.
  4. On the Confirmation screen, click Finish to create the queue.
  5. After creating both queues from Table 5 above, save the changes to the master configuration

Creating alias destinations on the service integration bus

Next you must create an alias destination for each of the queue destinations that you created above. For the sample application, the field values for each alias are summarized in Table 6 below. For the alias name, the WQ_ prefix must be used. The following steps walk you through each of the screens:

Table 6. Queue bus destination values
Destination typeIdentifierTarget identifierTarget bus
AliasWQ_IncomingQueueIncomingQueue<busName>
AliasWQ_OutgoingQueueOutgoingQueue<busName>
  1. On the Create new destination screen, select the Alias destination type.
  2. On the Set alias destination attributes screen, enter the alias name from Table 6 above for the Identifier field. The naming convention for each alias destination is WQ_ followed by the queue bus destination name. Be careful to enter the alias name correctly and without any added spaces, because misspelling the alias name can prevent the entire configuration from working properly.
  3. Skip the Target Identifier field. If the Target Bus dropdown is not already populated, then select the name of your bus from the Target Bus dropdown field. The Administrative Console interface automatically populates the Target Identifier field with values.
  4. Select the appropriate value from the Target Identifier field, as specified in Table 6 above.
  5. Leave default values for remaining fields, click Next, then click Finish on the Confirmation screen.
  6. Save the changes to the master configuration.

After the above changes have been completed, Queue Points are automatically created for the <nodeName>:<serverName> messaging engine for your SIBus. The queue points for the sample application are listed below:

  • IncomingQueue@<nodeName>:<serverName>-<busName>
  • OutgoingQueue@<nodeName>:<serverName>-<busName>

Messages sent to the JMS queues are stored and processed at the queue point. To view queue points, go to Service Integration =>Buses=> <busName> => Messaging Engines=> <nodeName>:<serverName>-<busName> => Queue points.

Creating the MDB listener port

The last resource you will configure for the sample application is the listener port for the IncomingMessageReceiverBean message-driven bean. Follow the steps below:

  1. In the Administrative Console, go to Servers => Application Servers => <serverName>.
  2. Under the Communications heading, expand the Messaging section and go to Message Listener Service.
  3. Under Additional Properties heading, click on Listener Ports.
  4. On the next screen, click New to create a new listener port. For the sample application, you will use the values shown in Table 7 below:
Table 7. Listener port values
Listener portQCF JNDIQueue destination JNDI
IncomingListenerPortjms/IncomingQCFjms/IncomingQueue

For your particular JMS application, if you are using message-driven beans, then the listener port name should match the value associated with your message driven bean, and the JNDI values should match with the JMS resources defined for your application.

  1. Click OK and then save the changes to the master configuration.
  2. Finally, restart your test server to make sure that all of the changes take effect.

Checking service integration security

If you do not have global security enabled for your WebSphere test server, skip this section and continue to Running the sample application below. If global security is enabled for your server, then bus and messaging security are enabled automatically by default and you should consider the following options:

  • Disable bus security. You can still enable global security without having bus security enabled.
  • Keep bus security enabled and perform additional steps to configure client authentication, authorization policies, and secure transport chains.

Configuring service integration security is beyond the scope of this article. For more information about administering service integration security, see Resources below. Here is how to disable bus security for your test server:

  1. In the Administrative Console, go to Service Integration => Buses => <busName>.
  2. If your WebSphere test server is V7.0 or later:
    1. Under Additional Properties, click on Security.
    2. Deselect the Enable bus security checkbox.
    3. Within the Permitted transports section, select Allow the use of all defined transport channel chains.
    4. Click OK and then save the changes to the master configuration.
    5. Restart your server.
  3. If your WebSphere test server is V6:
    1. Under General Properties, deselect the Secure checkbox .
    2. Click OK and then save the changes to the master configuration.
    3. Restart your server.

For more information about service integration security, see Resources below.

Running the sample application

The sample application lets you place text messages on the IncomingQueue and retrieve messages from the OutgoingQueue. The IncomingMessageReceiverBean message-driven bean automatically picks up any messages from the IncomingQueue and passes the message to the OutgoingMessageSenderBean stateless session bean. The OutgoingMessageSenderBean then puts the message on the OutgoingQueue. Two JSPs have been created to send messages to the IncomingQueue and retrieve from the OutgoingQueue. To run the application, following the steps below:

  1. Download the sample JMS application at the bottom of the article and unzip the file into a temporary directory.
  2. Import SampleJMSApplication.ear into an Enterprise Application project. Once imported, you should see the three projects shown in Figure 2 -- one Enterprise Application project, one EJB project, and one Dynamic Web project:
    Figure 2. Sample JMS Application projects
    Sample JMS Application projects
  3. Start up your test server and add the SampleJMSApplication project.
  4. Open a Web browser and enter http://localhost:<portNumber>/SampleJMSApplicationWeb/
    where <portNumber> is the port number associated with your application server.
  5. From the Put Message screen (see Figure 3), enter any text into the MessageText field and click Put Message to send a message to the IncomingQueue:
    Figure 3. Put Message screen
    Put Message screen
  6. To retrieve this message, click on Retrieve message from OutgoingQueue.
  7. From the Get Message screen (Figure 4), click Get Message to retrieve a message from the OutgoingQueue:
    Figure 4. Get Message screen
    Get Message screen

Conclusion

This article has shown you how to define two internal WebSphere V5 queues that simulate WebSphere MQ queues. You can use these same steps to configure additional queues for your specific JMS application. Once configuration is complete for your application, you can test your JMS application without being connected to a WebSphere MQ queue manager. The sample application showed how you can use this configuration to send messages to and retrieve messages from the simulated WebSphere MQ environment. You can now set up your own local test environment to verify whether your code handles incoming messages and sends outgoing messages correctly.


Download

DescriptionNameSize
Sample JMS Enterprise Application for this articleSampleJMSApplication.zip59 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=807203
ArticleTitle=Testing WebSphere JMS applications when disconnected from WebSphere MQ
publish-date=03282012