Introduction

The SOAP over JMS protocol support is limited to the use of JMS resources owned by the embedded (SIBus) JMS provider due to the automatic generation of these resources by the development tools. The runtime implementation uses the JMS API, so it's possible to enable the use of the WebSphere MQ JMS provider to transport SOAP messages (SOAP/MQ JMS) by replacing the generated JMS resources.

Find out how to configure imports and exports in WebSphere Process Server and WebSphere Enterprise Service Bus with Web service SOAP over JMS bindings to use WebSphere MQ JMS resources. This article provides example Service Component Architecture (SCA) applications that contain imports and exports with Web services-based SOAP over JMS bindings. It also describes how they are modified to use WebSphere MQ JMS resources. After reading this article, you can apply the steps described here to other such imports and exports.

The procedure is somewhat different between exports and imports. Exports make use of a message-driven bean (MDB) to receive requests, and they send responses to the destination specified by each request's JMSReplyTo header. You can modify their resources via the IBM WebSphere Application Server admin console.

Imports don't use an MDB to receive responses and can be configured to use a single reply queue or one temporary reply queue per request. Their resources are defined via a JMS URL in the WebSphere Integration Developer tool. For exports, the key difference between the WebSphere MQ JMS provider and the SIBus JMS provider is that the latter uses a Java 2 Platform, Enterprise Edition (J2EE) Connector architecture (JCA) resource adapter as its implementation. This means the MDB is configured by an activation specification object, while the former doesn't use JCA and is configured by a listener port object. WebSphere Integration Developer lets integration developers easily build and invoke a Web service using SOAP over JMS without writing complicated code. The Web service resource JNDI names are automatically generated by WebSphere Integration Developer, and the resources are automatically created using the SIBus JMS provider at installation time.

To perform these configuration procedures, you need the following software:

• WebSphere MQ V6.0 with Refresh Pack 6.0.2
• WebSphere Integration Developer V6.0.2 or V6.1
• WebSphere Process Server V6.0.2 or V6.1 or WebSphere Enterprise Service Bus V6.0.2 or V6.1

The application modules in this article have been developed and tested with both versions 6.0.2 and 6.1 of WebSphere Enterprise Service Bus. These modules are examples to demonstrate how to create and configure SCA modules using SOAP over JMS in WebSphere Integration Developer and WebSphere Process Server or WebSphere Enterprise Service Bus. The downloadable project interchange files are provided in WebSphere Integration Developer V6.1.

Back to top

WebSphere MQ versions

To use the WebSphere MQ JMS provider, make sure both the WebSphere MQ server and the WebSphere MQ JMS client library are installed on your system and that their versions are compatible. The WebSphere MQ JMS import and export binding has been supported in WebSphere Process Server and WebSphere Enterprise Service Bus since version 6.0.2, and this requires WebSphere MQ server of at least version 6.0 with the Refresh Pack 6.0.2.0. The WebSphere MQ JMS client library is shipped with the WebSphere Process Server and WebSphere Enterprise Service Bus run time.

You might need to change the value of the environment variable ${MQ_INSTALL_ROOT} to the value of ${WMQ_INSTALL_ROOT} from the WebSphere Application Server admin console if WebSphere MQ is local to the WebSphere Process Server or WebSphere Enterprise Service Bus run time. Alternatively, copy the JAR files com.ibm.mqjms.jar and com.ibm.mq.jar from ${WMQ_INSTALL_ROOT}/java/lib to ${WAS_INSTALL_ROOT}/java/lib. This ensures that the WebSphere MQ client library WebSphere MQ JMS versions used by WebSphere Process Server and WebSphere Enterprise Service Bus are compatible with the WebSphere MQ server.

Back to top

Resources required for point-to-point messaging

This section describes a procedure for defining WebSphere MQ and WebSphere MQ JMS resources that can then be used by an import or export with a Web service SOAP over JMS binding. The names of the resources provided here are examples that you can change as required. First you find out how to work with the point-to-point messaging model using queue destinations. Later, in the Resources required for publish/subscribe messaging section, you learn how to work with the messaging model using topics. There are two ways to create a WebSphere MQ queue manager and queues:

• Create them from the WebSphere MQ Explorer.
• Create them from a command line window using WebSphere MQ commands.

For example, from a command line window, you enter> crtmqm QMGR to create a queue manager and strmqm QMGR to start the queue manager. (See Resources for a link to the WebSphere MQ V6.0 Information Center, which has details on how to create the required objects.)

This procedure requires the following WebSphere MQ queue manager and queues to be created:

• WebSphere MQ queue manager: QMGR
• WebSphere MQ queues: REQUESTQ and RESPONSEQ on QMGR for use with the export with Web service SOAP over JMS binding
• WebSphere MQ queues: REQUESTQ1 andRESPONSEQ1 on QMGR for use with the import with Web service SOAP over JMS binding

Corresponding to these WebSphere MQ resources, you need to create WebSphere MQ JMS Provider resources in the WebSphere Enterprise Service Bus or WebSphere Process Server admin console. You must create these resources under the WebSphere MQ JMS Provider at the node scope. Use the following steps to create the resources required for an export and import configuration:

1. Create a WebSphere MQ queue connection factory used for request connections for both export and import: requestMQCF, which uses QMGR.
2. Create a WebSphere MQ JMS queue connection factory used for reply connections for both export and import: replyMQCF using QMGR.
3. Create a WebSphere MQ JMS queue destination for receiving a request message at an export: requestQ using REQUESTQ.
4. Create a WebSphere MQ JMS queue destination for sending a request message from an import: requestQ1 using REQUESTQ1.
5. Create a listener port on the server: MQListener, which uses requestMQCF and requestQ, as shown in Figure 1.
6. Create a listener port on the server: MQListener1, which uses requestMQCF and requestQ1, as shown in Figure 1.
   
   Figure 1. Example of user-defined listener ports
   
   
   
7. Create a WebSphere MQ queue destination for sending a response message: replyQ using RESPONSEQ.

Note: This queue is used by a client application as the destination to which replies are to be sent, specified via the JMSReplyTo header in JMS messages. This destination is not configured against the Web service SOAP over JMS export or import bindings.

Back to top

Application scenario for the point-to-point messaging model

The point-to-point scenario detailed in this section uses three applications, as shown in Figure 2.

• The WSMQJMSClient: Web application that uses a JavaServer Pages (JSP) sendMessage.jsp to send SOAP messages.
• WSMQJMSBackEndService: Web service with SOAP over JMS using WebSphere MQ resources, whose implementation invokes another Web service.
• WSMQJMSServiceProvider: Another Web service provider using WebSphere MQ resources. Messages flow between these applications as follows:
1. The client sends a SOAP message to a defined WebSphere MQ queue.
2. The SOAP message is converted from the WebSphere MQ queue into a business object using an export with a Web service SOAP over JMS binding.
3. A Java component handles the message and invokes another Web service provider via an import with a Web service SOAP over JMS binding.
4. The Java component returns a response message to the defined WebSphere MQ queue via an export with Web service SOAP over JMS binding (when the request operation is a request/response operation).

Create an application with a SOAP over JMS export binding

This application is designed to have an export with a Web service SOAP over JMS binding and a Java component with the implementation of the interface of the Web service. This export receives SOAP messages sent by a JMS client application. The SOAP messages are then converted by the run time into business objects for use by components within the application. This application is provided as an example, which is then modified to use WebSphere MQ JMS resources; you can apply the same procedure to your own exports with Web service SOAP over JMS bindings. Let's break this down:

1. Create a library called MyLibrary, which contains a CustomerService interface with three functions, as shown in Listing 1.
   
   Listing 1. CustomerService interface
   

   CustomerInfo getCustomerInfo(String id); void createCustomer(String id); int getQuantity(String id);

   
   
2. Create a module called WSMQJMSServiceProvider, which has an export with a Web service SOAP over JMS binding and a Java component from WebSphere Integration Developer. The ProviderSOAPMQJMSExport has the Web service SOAP over JMS binding as shown in Figure 3.
   
   Figure 3. WSMQJMSServiceProvider application
   
   
   
3. Make sure this application depends on MyLibrary.

Build the Web service application

To build and install the project from WebSphere Integration Developer, perform the following steps:

1. Build the project WSMQJMSServiceProvider.
2. Choose File > Export > Export project to integration module export to export the project to an .ear file: WSMQJMSServiceProvider.ear.
3. Start the WebSphere Process Server or WebSphere Enterprise Service Bus run time.
4. Install the .ear file from the WebSphere Application Server admin console.

Install and modify the application to use WebSphere MQ JMS

The application has to be installed from the WebSphere Application Server admin console so that you can change some resources either during or after installation. For an export with a Web service binding, nothing needs to be changed before the installation. The first installation method works for WebSphere Process Server and WebSphere Enterprise Service Bus V6.0.2; it also works in WebSphere Process Server and WebSphere Enterprise Service Bus V6.1 if the show me more installation options and parameters option is enabled at the first step of the installation. The second method works the same in both version 6.0.2 and 6.1 and is shown later in this article.

Note: There's no requirement to install the WebSphere MQ resource adapter, as WebSphere MQ has been supported since WebSphere Process Server V6.0.2.

Method 1: Specify MQ JMS resources during installation:

1. Install the WSMQJMSServiceProvider.ear file.
2. At step 6 of the installation, select the listener port and specify it as MQListener1, defined earlier as the binding for the WebServicesJMSRouter_ProviderSOAPMQJMSExport_CustomerServiceJmsPort, as shown in Figure 4 (see a larger version of Figure 4).
   
   Figure 4. Configure listener port for SOAP/MQJMS export
   
   
   
3. At step 8 of the installation, called Map resource references to resources, select none under specify authentication method by selecting ProviderSOAPMQJMSExport and clicking the Apply button.
4. Change the export Enterprise JavaBeans (EJB) WebServicesJMSRouter_ProviderSOAPMQJMSExport _CustomerServiceJmsPort JNDI name from jms/WebServicesReplyQCF to replyMQCF, as shown in Figure 5 (see a larger version of Figure 5).
   
   Figure 5. Mapping JNDI names and WebSphere MQ resources
   
   
   
5. Use the default settings in the rest of the installation.
6. Don't change the module JNDI name, because the module EJB uses the SIBus JMS connection factory to support asynchronous communications with other SCA modules.
7. Start the application, and make sure the listener port, MQListener1, is started.

Create an application with import and export that has Web service SOAP over JMS bindings

The application covered here includes:

• An export with a Web service SOAP over JMS binding, used for receiving SOAP messages and converting them into business objects.
• A Java component implementation, which prints the data field in the business object.
• An import with a Web service SOAP over JMS binding, which invokes the WSMQJMSServiceProvider.

The application is created in WebSphere Integration Developer and is shown in Figure 6. This illustrates the second method of modification to use WebSphere MQ JMS by configuring the JNDI resources after installation.

After you create this application, perform the following steps:

1. Select CustomerServiceImport1, and modify the destination and connection factory values of the address property, as shown in Figure 7 (see a larger version of Figure 7). The updated value for the address property is:
   
   Listing 2. The Web service import with SOAP over JMS binding address property
   

   jms:/queue?destination=requestQ1& connectionFactory=requestMQCF& targetService=ProviderSOAPMQJMSExport_CustomerServiceJmsPort

   
   
   
   Figure 7. The SOAP/MQJMS import property
   
   
   
2. Build the application.
3. Export the application into an .ear file: WSMQJMSBackEndService.ear.
4. Install the .ear file as default without changing anything.
5. Change the resources after installation; go to the list of the installed applications.
6. Double-click the WSMQJMSBackEndServiceApp application to the configuration, as shown in Figure 8.
   
   Figure 8. Application configuration
   
   
   
7. Change the listener binding for MDBs (this is the same as method 1 step 2), and specify MQListener as the listener port.
8. Change the map resource references to resources step in the same way as method 1 step 3, as shown in Figure 9, and change the export EJB WebServicesJMSRouter_ BackEndSOAPMQJMSExport_CustomerServiceJmsPort JNDI name from jms/WebServicesReplyQCF to replyMQCF.
   
   Figure 9. Modifying resources reference
   
   
   

Create a SOAP/MQ JMS client application

This section describes the required behaviour of client applications that send SOAP messages to the WebSphere MQ JMS destination, which then correspond to the reconfigured export from earlier steps. The format and the properties of the SOAP messages have to be provided in an appropriate way so that the messages are consumed correctly by the SOAP over JMS export. Listing 3 shows an example of a SOAP message for a one-way message using the CustomerService interface defined earlier.

                
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:q0="http://MyLibrary/CustomerService"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <SOAP-ENV:Body>
  <q0:createCustomer>
   <id>123</id>
  </q0:createCustomer>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following three JMS user properties must be set in messages sent to a SOAP over JMS export:

• targetFunctionName: The name of the operation (function) in the CustomerService interface to be invoked. In this example the value must be either createCustomer or getCustomerInfo.
• JMSReplyTo: The destination for the response message is set to replyQ.
• targetService: The Web service port name. The value must be BackEndSOAPMQJMSExport_CustomerServiceJmsPort. Figure 10 shows an example of a client application implemented as a JSP that sends a SOAP message to the requestQ and gets the response back from the replyQ.
  
  Figure 10. Client application sends a request message
  
  
  

After clicking the sendMessage button, the runtime displays in a console window, as shown in Figure 11, and a response message is received back to the JSP client, as shown in Figure 12.

You can also use the RFHUtil tool (see Resources for more information) to view a SOAP message on the WebSphere MQ queues. RFHUtil lets you read and write data from and to files or queues, and display data in a variety of formats. Figure 13 shows an example of a SOAP message from the RESPONSEQ destination by using RFHUtil 5.0.5.

Back to top

Resources required for publish/subscribe messaging

This section describes how to use the publish/subscribe model with imports and exports with Web service SOAP over JMS bindings, using the WebSphere MQ JMS provider.

Create WebSphere MQ resources

The publish/subscribe model is designed for an application (the publisher) to send messages to a set of interested applications (the subscribers). Subscribers register their interest in a particular topic, and publishers indicate the topic relevant to their messages. A broker sits in between the publisher and subscribers and sends a copy of each message under a certain topic to the appropriate subscribers. WebSphere MQ includes an embedded broker. To use the publish/subscribe model with WebSphere MQ, you need to configure the following WebSphere MQ resources from the WebSphere Enterprise Service Bus or WebSphere Process Server admin console at the Node scope:

1. Create a WebSphere MQ JMS topic connection factory. The transport type must be a CLIENT, and the resources have been highlighted, as shown in Figure 14. The broker version is basic, letting you use the WebSphere MQ embedded broker.
   
   Figure 14. Configuration of the WebSphere MQ topic connection factory
   
   
   
2. Create a WebSphere MQ JMS topic destination called MQTopicDest with a JNDI name, MQTopicDest, and a basic topic name, Greetings, as shown in Figure 15.
   
   Figure 15. Configuration of the WebSphere MQ topic with JNDI name MQTopicDest
   
   
   
3. Create an WebSphere MQ JMS listener port called MQTopicListener, which uses MQTopicCF and MQTopicDest, as shown in Figure 1.

Configure a WebSphere MQ broker service

To use the WebSphere MQ broker service, there's an initial setup step required only the first time you use the broker. This creates a number of queues, including SYSTEM.BROKER.CONTROL.QUEUE, which is used to handle subscription messages:

$WMQ_INSTALL\Java\bin runmqsc QMGR <MQJMS_PSQ.mqsc

If the broker isn't running, then start up the SYSTEM.BROKER either from a command-line window, using the command $WMQ_INSTALL/bin strmqbrk –m MQGR, or start the broker from the WebSphere MQ Explorer, as shown in Figure 16 (see a larger version of Figure 16).

An application scenario for the publish/subscribe model

This application scenario is designed for both a publisher and a subscriber so that they can use WebSphere MQ resources to communicate with SOAP messages. Figure 17 is an example of the application scenario. It includes a WSMQJMSPublisher application and a WSMQJMSSubscriber application. WSMQJMSPublisher is a client application for publishing messages to the MQTopicDest topic. WSMQJMSSubscriber is a Web service application that subscribes to the MQTopicDest topic to receive SOAP messages.

Create an interface with a one-way operation

When using publish/subscribe with an import or export with Web service SOAP over JMS binding, only one-way operations are supported. So an interface with only one-way operations is required. Create the interface using the following steps:

1. Create a new interface called GreetingService under MyLibrary.
2. Create a one-way operation in the interface: void sayHello(String message);
3. Save and build MyLibrary.

Create a subscriber application

1. In WebSphere Integration Developer, create a new module called WSMQJMSSubscriber with an export with a Web service SOAP over JMS binding called SubscriberSOAPMQJMSExport and a Java component called HandleTopic, as shown in Figure 18.
   
   Figure 18. Example of a Web service application
   
   
   This module illustrates the use of a WebSphere MQ JMS topic by an export with a Web service SOAP over JMS binding.
2. Open the WSDL file called WSMQJMSSubscriber_SubscriberSOAPMQJMSExport.wsdl in MyLibrary, and change the message type from queue to topic so the SubscriberSOAPMQJMSExport binding address property looks like Listing 4.
   
   Listing 4. A web service export with SOAP JMS binding address property
   

   jms:/topic?destination=jms/SubscriberSOAPMQJMSExport& connectionFactory=jms/SubscriberSOAPMQJMSExportQCF& targetService=SubscriberSOAPMQJMSExport_GreetingServiceJmsPort

   
   You can't change this from the SOAP over JMS export property window shown in Figure 19.
   
   Figure 19. WSMQJMS Export property
   
   
   This ensures that the export knows to subscribe to a topic to receive request messages. The implementation of the HandleTopic method simply prints out a message in the method— sayHello(String message) —, which is passed by SubscriberSOAPMQJMSExport.
3. Save the changes to build the WSMQJMSSubscriber application.

Deploy and install the subscriber application

Export the WSMQJMSSubscriber application to an EAR file, and install it from the WebSphere Enterprise Service Bus or WebSphere Process Server admin console. The steps are the same as before (see the Install and modify the application to use WebSphere MQ JMS section), except this time only change the activation specification to the listener port MQTopicListener.

Create a publisher application

This section describes how to create an example publisher application, which makes use of an import with a Web service SOAP over JMS binding. We've chosen to create a module that contains only an import with Web service SOAP over JMS binding. The following steps show you how to create one:

1. Create a new module called WSMQJMSPublisher.
2. Navigate to MyLibrary > Web Service Ports > SubscriberSOAPMQJMSExport_GreetingServiceJmsPort.
3. Drag the SubscriberSOAPMQJMSExport_GreetingServiceJmsPort onto the WSMQJMSPublisher Assembly Diagram to create an import with the Web service SOAP over JMS binding.
4. Change the import component name into GreetingServiceSOAPMQJMSImport.
5. Change the value of the Address property to what's shown in Listing 5.
   
   Listing 5. Web service import with SOAP over JMS binding address property for a topic destination
   

   jms:/topic?destination=MQTopicDest& connectionFactory=MQTopicCF& targetService=SubscriberSOAPMQJMSExport_GreetingServiceJmsPort

   
   You can directly change this from the import's Web service binding property window, shown in Figure 20.
   
   Figure 20. WSMQJMSPublisher and the import property
   
   
   
6. Build the module and export it as an EAR file.

Test the publisher application from WebSphere Integration Developer

From WebSphere Integration Developer, you add the publisher application to the currently running server:

1. Right-click the project TestWSMQJMSPub and choose Test > Test Module (see Figure 21).
   
   Figure 21. Test publisher result
   
   
   
2. Enter a string, such as hello, in the message field; the message is then published under the topic Greetings.
3. The subscriber receives the message and prints it out exactly as shown in the console window.

Back to top

Conclusion

This article used both the point-to-point messaging model and the publish/subscribe messaging model to demonstrate how to configure WebSphere MQ resources used by Web service SOAP over JMS bindings. For the point-to-point messaging model, you change the export to use a WebSphere MQ JMS message listener and modify the export reply connection factory into a WebSphere MQ JMS connection factory during or after the application installation time. For the import, you only need to modify the address property: place the destination into a predefined WebSphere MQ JMS queue destination, and place the connection factory into a predefined WebSphere MQ JMS connection factory before the application installation. For a request/response message, the client application has to set the JMSReplyTo header in JMS messages.

For the publish/subscribe message model, you change the export binding address property to make the destination type topic. You also need to change the export from a JCA activation specification into a predefined WebSphere MQ JMS listener port during or after the application installation time. For the import, you change the destination into a WebSphere MQ JMS topic destination and change the connection factory into a WebSphere MQ JMS topic connection factory before the application installation.

Back to top

Downloads

Information about download methods

Resources

Learn

• Read the article, "Building a JMS Web service using SOAP over JMS and WebSphere Studio" (developerWorks, Feb 2004).
  
  
• Get more information in the article, "Web services client programming for WebSphere Process Server" (developerWorks, Aug 2006).
  
  
• Check out the IBM WebSphere Developer Technical Journal "Deploying publish and subscribe applications into the Service Integration Bus (developerWorks, Aug 2005).
  
  
• The SOA and Web services zone on IBM developerWorks hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  
• Play in the IBM SOA Sandbox! Increase your SOA skills through practical, hands-on experience with the IBM SOA entry points.
  
  
• The IBM SOA Web site offers an overview of SOA and how IBM can help you get there.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.
  
  
• Check out a quick Web services on demand demo.
  
  
• Get an RSS feed for this series. (Find out more about RSS.)
  
  

Get products and technologies

• Innovate your next development project with IBM trial software, available for download or on DVD.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the authors

Dr. Fenglian Xu works as a software developer in the WebSphere Enterprise Service Bus development team at IBM Hursley Lab in the UK. Her expertise includes the JMS and Web services over JMS bindings in WebSphere Enterprise Service Bus and WebSphere Application Server. She has worked in various IT companies from middleware to application for 10 years. She has gained her main expertise in Java, J2EE, and SOA. She obtained her PhD degree in computer science from the University of Southampton in 1998.

Simon Holdsworth has worked as a software engineer at IBM's Hursley Lab for over 15 years on a variety of projects. These include mainframe assembler programming, C, C++, and most recently Java. Simon is currently responsible for the overall software architecture and high-level design for connectivity of IBM WebSphere Enterprise Service Bus and WebSphere Process Server products, and he's the chairman of the OASIS SCA Bindings technical committee. He has been designing and implementing systems that support Web services since 2001. During this work on leading-edge technologies, Simon has gained 15 patents and is an IBM Master Inventor.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• WebSphere MQ versions
• Resources required for point-to-point messaging
• Application scenario for the point-to-point messaging model
• Resources required for publish/subscribe messaging
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers