This topic explains how to use the JMS transport with SOAtest, as well as supporting tools and provisioning action tools in Virtualize.

It includes the following sections:

JMS Prerequisites

If you are using SOAtest or Virtualize tools as a JMS client, we recommend that SOAtest or Virtualize consult a JNDI provider to make connections to the JMS middleware. For this to happen, a JNDI Provider needs to be set up and all necessary jar files (i.e. ones containing the Initial Context) need to be added to the SOAtest or Virtualize classpath. (For more information on how to add jars to the classpath, see System Properties Settings). You will also need to supply the names of the connection factory, destination, and reply-to queue that the JNDI provider will look up.

If your JMS setup does not have a JNDI provider that SOAtest or Virtualize can query for an instance of a ConnectionFactory, follow the instructions in JMS Messaging without JNDI. Alternatively, you can set up a simple file system JNDI provider.  The .jars and documentation for such a provider are available from the Oracle Java site. Setting up a file system provider is quite easy and the documentation is included in the download.  Once the provider is ready, use the piece of simple Java code as described in Configuration for Popular JMS Providers to create an instance of the ConnectionFactory to connect to the JMS server using the host and port as arguments. The same should be done for Topics and Queues used by this product. 

Configuring JMS Options 

After selecting JMS from the Transport drop-down menu within the Transport tab of an appropriate tool, the following options display in the left pane:

Connection Settings

Connection Settings contains Settings and Properties tabs for JNDI Initial Context

The Properties tab is optional and allows you to specify additional properties to be passed to the JNDI javax.naming.InitalContext constructor (in addition to the Provider URL and Initial Context factory properties that are specified in the Settings tab). Property values, which can be added by clicking Add and completing the Add JMS Property dialog,  can be set to a fixed value, a parameterized value, a scripted value, or a unique value (an automatically-generated random unique value—no two tool invocations will use the same value).

The Settings tab contains the following:

In addition to the Settings tab, the Connection Settings also include:


The Queue/Topic settings contain the following options:

Messaging Model

Messaging Model options specify how messages are sent between applications. Select either Point to Point or Publish and Subscribe.

Messaging Expiration

The Messaging Expiration option specifies the message expiration time (in milliseconds).

Message Exchange Pattern

Message Exchange Pattern options specify whether or not SOAtest or Virtualize receives a response. If Get Response is selected, SOAtest or Virtualize sends a message and receives a response. If Get Response is not selected, SOAtest or Virtualize sends a one-way message and does not receive a response.

If Get Response is selected, you can also enable Create message consumer on the JMSReplyTo destination before sending the message. If the response is expected to become available very quickly on the JMSReplyTo topic, this option should be enabled to ensure that SOAtest or Virtualize has subscribed to the reply topic before the response message is published.

This option is cannot be mixed with Match response JMSCorrelationID with the request JMSMEssageID because the JMS specification requires vendors to generate the JMSMessageID after the message is sent. As a result, there is no way to create the consumer on the response destination with that correlation (selector) set until after the message has been set and the JMSMessageID becomes available. 

Message Type

Message Type options allow you to select the message type from the drop-down menu. A JMS Message is a Java object that contains the data being transferred between JMS clients. The following Message Types are available:

Request Message Properties

The Request Message Properties are optional and allows for any miscellaneous property values to be set into the javax.jms.Message object before it gets sent to a queue or published to a topic. These include predefined properties that get set to the outgoing requests message using one of the corresponding "set" methods in javax.jms.Message, or custom properties (for example, properties set with setStringProperty, setBooleanProperty, setByteProperty, etc.)

Property values, which can be added by clicking Add and completing the Add JMS Property dialog,  can be set to a fixed value, a parameterized value, a scripted value, or a unique value (an automatically-generated random unique value—no two tool invocations will use the same value). Be sure to specify the type for each added value.

Response Message Correlation

The Response Message Correlation settings contain the following options:

Message Object Outputs for Clients Using JMS

You can add message object outputs to Messaging Clients that use the JMS transport. You can also add incoming JMS message outputs to Call Back tools that use the JMS transport. You can chain an Extension tool, for example, to a Messaging Client that uses JMS so that it has access to the response JMS Message. In the ObjectMessage case, you can use getter and equals() methods to validate the response thereby creating a regression control. In addition you can chain a Diff tool to the Response Traffic and if the response is an ObjectMessage, SOAtest will convert the inserted serializable object to XML format and perform an XML diff. By doing this you can use data bank values, ignore XPath differences, etc.

To do this complete the following:

  1. Right-click the Messaging Client or Call Back tool node and choose Add Output from the shortcut menu. The Add Output wizard displays.

  2. Choose Response> Message Object (or Incoming Request> Incoming JMS Message for Call Back tools) in the left pane. 
  3. Choose New Output or Existing Output and the desired tool (e.g., an Extension tool) from the right pane.
  4. Click Finish button. SOAtest adds the new output to the selected node.

Configuration for Popular JMS Providers

See JMS Provider Configuration

Responding to a Temporary JMSReplyTo Queue

To respond to a JMS message with a temporary queue set in the JMSReplyTo field:

  1. Create a Call Back Tool and configure it to receive the JMS message.
  2. Right-click the Call Back Tool and choose Add Output> Incoming JMS Message>  Extension tool.
  3. Write a custom script that places the incoming message (input object) into the scripting context with a predetermined key.
  4. Create and configure the tool that will send the JMS response message.

SOAtest will then use the temporary queue of the received message as the destination in place of the keyword entered as the destination.

Using Message Selector Filters

In various tools, you can specify a value to act as a message filter. This is specified in a field labelled Message Selector or Additional Selector Expression Terms.

For example, by entering username==John, only messages that contain "John" as a username will be delivered. If this field is left blank, then any messages can be received.

Here are some tips for working with message selector filters:

JMS Messaging without JNDI

Using JNDI in order to obtain JMS connection factory and Destination instances is highly recommended from an architectural perspective because it decouples JMS consumer code from vendor-specific dependencies. In test or staging environments, a JMS system occasionally does not have a JNDI configured yet, or the JNDI does not yet include the desired connection factories. Furthermore, it might be helpful to bypass JNDI during testing in order to debug issues or isolate system performance characteristics with and without JNDI.

For these reasons, SOAtest's or Virtualize's JMS-aware tools allow for sending and receiving JMS messages using vendor connection factories directly—without going through JNDI—as long as your JMS provider permits this. 

This capability supports certain JMS implementations that are designed to allow for JMS connections to be established without JNDI in the first place, and which provide connection factory classes with a constructor that takes a single string argument as the connection URL.

Supported JMS Implementations

Since this support for JMS messaging without JNDI is not based on standard JMS API, it is not guaranteed to be portable across different JMS implementations. 

This capability has been tested with Sonic and TIBCO JMS. It is also supported for WebSphere MQ, with the configuration described in IBM WebSphere MQ (MQ Series).

At the time of this writing, the direct creation of connection factories for Oracle/BEA WebLogic, JBoss, or WebSphere Default JMS provider is not supported by SOAtest or Virtualize and in most of these cases, it is not documented or encouraged by these vendors. 


To configure one of the JMS messaging tools in SOAtest or Virtualize to send/receive messages without JNDI:

The empty Initial Context field is interpreted as a signal to instantiate the connection factory object directly and without JNDI. It will attempt to do so with a constructor that takes a single string argument, passing in the connection URL that you specified in the Provider URL field. The connection authentication settings will still be used as usual. If no such constructor exists in your provider's connection factory API, then JNDI is needed in order to instantiate the connection factory class.

For example, in the case of Sonic JMS, the Connection Factory class name to be provided would be progress.message.jclient.ConnectionFactory. For TIBCO JMS, it would be com.tibco.tibjms.TibjmsConnectionFactory. On the other hand, JBoss and OpenJMS do not have a connection factory that takes a single connection URL argument. In these cases, there must be a JNDI in order to exchange JMS messages with these systems using SOAtest or Virtualize.

Regardless of the JNDI settings configuration, SOAtest and Virtualize will always attempt to resolve the destination (queue or topic) name from JNDI if JNDI exists and if the name exists in the directory. If it cannot find it via JNDI, then it will attempt to create the destination directly from the JMS Session instance—assuming that the user-provided name is the physical destination name and not a JNDI name.

Note that Sun's JNDI implementation is available as well. See Sun JMS for details.

Browsing Queue Contents

The Queue Browser allows you to see the contents of queues deployed on Websphere MQ, Websphere Application Server, Tibco EMS, Sonic MQ, ActiveMQ, and any other JMS provider. See Browsing Queues in SOAtest and Browsing Queues in Virtualize for details.