Web services with SOAP over JMS in IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus, Part 1: Using the SIBus JMS provider

Fenglian Xu (xufengli@uk.ibm.com), Software Engineer, IBM　

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 (Simon_Holdsworth@uk.ibm.com), Senior Technical Staff Member, IBM　

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.

Summary: This two-part article series shows you how to use SOAP over Java™ Message Service (JMS) in IBM® WebSphere® Process Server and IBM WebSphere Enterprise Service Bus. Learn how to set up and use SOAP over JMS as configured by default by the IBM WebSphere Integration Developer tool and how to enable the use of the IBM WebSphere MQ JMS provider via configuration. In this article, Part 1 of the series, you create and invoke a Web service using SOAP over JMS and an end-to-end application example, covering the full process of creating, building, deploying, and testing the applications. Scenarios covering both point-to-point and publish/subscribe messaging walk you through the process. In the second article in this series, you'll reconfigure a Web service that uses the SOAP over JMS protocol to enable the use of WebSphere MQ as the JMS provider and allow the transport of SOAP messages via WebSphere MQ queues.

View more content in this series

Tag this!

Date: 22 May 2008
Level: Intermediate
PDF: A4 and Letter (655KB)Get Adobe® Reader®
Activity: 14843 views

Introduction

Typically, HTTP is an unreliable protocol to use for delivering Web service messages. So when you need more reliability, you might need an alternative protocol. And increasingly, existing or new JMS applications are being written to handle SOAP message payloads. WebSphere Process Server and WebSphere Enterprise Service Bus both support the use of JMS to deliver Web service messages to provide greater reliability and the ability to integrate with JMS applications that use the SOAP protocol.

This support is provided as a Web service binding that you can apply to WebSphere Process Server and WebSphere Enterprise Service Bus module exports (the points at which services are provided) and imports (the points at which services are invoked). You can configure the binding to use either HTTP or JMS to transport SOAP messages. When an export with a Web service binding is wired to a component, the run time automatically handles the Web services protocol and translation of the SOAP message into the form required by the component. Similarly, when a component is wired to an import with a Web service binding, the run time automatically handles the invocation of the Web service.

When SOAP over JMS is selected for the Web service binding, the WebSphere Application Server default JMS provider—also known as the Service Integration Bus (SIBus) JMS provider—is used to create the necessary resources to provide or invoke the Web service.

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 Java Naming and Directory Interface (JNDI) names are automatically generated by WebSphere Integration Developer using the SIBus JMS provider.

Software requirements

To follow along with this article, you need the following software installed on your machine:

WebSphere Integration Developer V6.02 or V6.1
WebSphere Process Server V6.02 or V6.1, or WebSphere Enterprise Service Bus V6.02 or V6.1

The examples have been developed and tested with both versions 6.02 and 6.1. The downloadable project interchange files are provided from WebSphere Integration Developer V6.1.

Messaging models

JMS applications interact in one of two ways:

Point to point: When there are two applications that interact directly, the messaging model is called point to point, and the JMS resource that's used is a queue.
Publish/subscribe: When there's an independent set of applications producing information and another set consuming that information, the messaging model is publish/subscribe, and the JMS resource that's used is a topic.

Both point to point and publish/subscribe messaging models are demonstrated by example applications so you can understand which JMS JNDI resources you need to build Web services with SOAP over JMS in WebSphere Integration Developer.

The automatically generated JNDI names and their corresponding resources are used for the point-to-point messaging model. To use the publish/subscribe messaging model, the JNDI names and their corresponding resources have to be reconfigured in both the deployment descriptor and Admin Console.

Application scenario for the point-to-point messaging model

This scenario demonstrates a Web service provided by a module that uses the SOAP over JMS Web service binding and is invoked by another module that uses the same binding. In this case, the point-to-point messaging model is used where the sender and receiver of messages use the same JMS destination. One JMS destination is used for request messages and one for response messages, as illustrated in Figure 1.

Figure 1. Example of the point-to-point scenario using SOAP over JMS binding

Figure 1 shows an example of the use of SOAP over JMS with the point-to-point messaging model. The Web service application WSJMSBackEndService includes an export with a Web service SOAP over JMS binding and a Java component. The export handles Web service processing on receiving and sending SOAP over JMS messages, and invokes the Java component via its interface. The Java component provides the implementation of the back-end service; it's unaware that the SOAP over JMS protocol is being used to invoke it.

The WSJMSMessageSender application has an import with a Web service SOAP over JMS binding, which invokes the WSJMSBackEndService by putting messages on the request destination and reading messages from the reply destination. Request messages indicate the response destination using the JMSReplyTo header field when required.

Create a Web service with SOAP over JMS for point-to-point messaging

First you create a library with shared interfaces, which the applications in this article use. This library has one interface, called CustomerService, with three operations. Follow these steps to create an interface and a business object (BO) in WebSphere Integration Developer:

To create a library in the business integration perspective, select New > Library to bring up a wizard, then type MyLibrary as the name. Click Finish.
To create a BO in MyLibrary, select Data Type > New > Business Object. Enter data in the fields as shown in Figure 2.

Figure 2. An example of BO with five fields
To create an interface called in MyLibrary, right-click Interface > New, and enter CustomerService as the name in the wizard. Click Finish.
Create three operations in CustomerService, as shown in Figure 3 (see a larger version of Figure 3).

Figure 3. An example of Interface with three operations

The CustomerService interface is used by Service Component Architecture (SCA) components in the example applications.

Now follow the next steps to create a Web service with SOAP over JMS implemented by a Java component in WebSphere Integration Developer:

Create a new module clicking File > New Module and entering WSJMSBackEndService as the module name in the wizard. Click Finish.
Create a SOAP over JMS export by dragging the Export icon into the assembly diagram and generating a Web service SOAP over JMS binding with the default settings.
Create a Java component called HandleRequest with the interface CustomerService.
Wire up the BackEndSOAPJMSExport and the HandleRequest component, as shown in Figure 4.

Figure 4. WSJMSBackEndService application

Right-click the HandleRequest component to generate the implementation. Listing 1 shows an example of the implementation code.

Listing 1. Snippet of the implementation of HandleRequest

                        
public DataObject getCustomerInfo(String id) {
   ServiceManager serviceManager = ServiceManager.INSTANCE;
   BOFactory bof = (BOFactory) serviceManager
   .locateService("com/ibm/websphere/bo/BOFactory");

   if( bof == null ) System.out.println("bof == null");

   DataObject myData = bof.create("http://MyLibrary/data/ibm/com",
                                  "CustomerInfo");
   System.out.println("Creating a CustomerInfo object with soap/jms -------");
   myData.setString("id", id);
   myData.setString("firstName", "Lisa");
   myData.setString("lastName", "Frank");
   Date shipDate = new Date();
   myData.setDate("shipDate", shipDate);
   myData.setInt("quantity", 40);
	    
   System.out.println("the created customerInfo is returned: ");
   printCustomerInfo(myData);

   return myData;
}

The printCustomerInfo(myData) is a private function that prints out the value of the myData object.

View the export binding properties by selecting BackEndSOAPJMSExport from the assembly diagram, as shown in Figure 5.

Figure 5. Web Service SOAP over JMS export binding properties

The address property includes these JMS resources:

Message type
Destination
Connection factory

The values of these resources are automatically generated and stored in the BackEndSOAPJMSExport_CustimerServiceJmsPort.wsdl file under MyLibrary when a SOAP over JMS binding is generated in WebSphere Integration Developer. The destination is used to receive request messages. The connection factory is used to connect to the JMS provider (in this case the SIBus JMS provider) and to access the destination.

Now you can save and build the WSJMSBackEndService project:

Export the WSJMSBackEndService project into an .ear file, WSJMSBackEndService.ear, and install it from the Admin Console.
Install the WSJMSBackEndService.ear file from the Admin Console, taking the default settings for each step. You might need to start the installed application from the Admin Console manually.

The implementation of the Web service SOAP over JMS binding, when used for an export, uses a message-driven bean (MDB) to receive request messages. This MDB and the resources required are created during the installation process using the JMS resources above and the SIBus JMS provider. The resources created include the JMS activation specification shown in Figure 6 (see a larger version of Figure 6) and the connection factory that's used for both request and response messages in Figure 7 (see a larger version of Figure 7).

Figure 6. Activation specification created for the export MDB

Figure 7. JNDI resources for both request and response connection factories

Create a client application for the point-to-point messaging model

In WebSphere Integration Developer, you can create a Web service client application by using an import with a Web Service SOAP over JMS binding:

Create a new module called WSJMSMessageSender.
Navigate to BackEndSOAPJMSExport_CustimerServiceJmsPort under MyLibrary in the business integration perspective.
Drag the BackEndSOAPJMSExport _CustomerServiceJmsPort and drop it into the assembly diagram.
In the resulting dialog box, select the Import with Web Service Binding option to create a CustomerServiceImport1, as shown in Figure 8.

Figure 8. Example of creating the MessageSender application
View the Binding properties of the import by selecting the CustomerServiceImport1 in the assembly diagram, as shown in Figure 9.

Figure 9. SOAP over JMS import binding property

Note: This address property is the same as the export's SOAP over JMS binding address property shown in Figure 5.

The destination in an import is for sending SOAP over JMS request messages. The connectionFactory in an import is used to connect to the JMS provider (in this case the SIBus JMS provider) and to access the request and reply destinations.

When the module is deployed, there are no JMS JNDI resources created for the import, because it uses the referenced export resources.

Test the WS SOAP over JMS import application with the test module

You can test the WSJMSMessageSender from WebSphere Integration Developer using the test module capability. This assumes that you've configured a WebSphere Process Server or WebSphere Enterprise Service Bus run time in the server configuration:

Start the server from WebSphere Integration Developer.
Add the WSJMSMessageSender project to the server.
Right-click WSJMSMessageSender to test the module.
Select an operation to test, such as getCustomerInfo, and enter the value for the ID parameter.
Click the Run button to invoke the getCustomerInfo in the WSJMSBackEndService. The getCustomerInfo function is called as shown in the console window. The CustomerInfo object is returned and displayed in the test window, as shown in Figure 10.

Figure 10. Test module and invocation results

You can also test the WSJMSMessageSender project without installing it first, because the test installs and starts the WSJMSMessageSender if it hasn't already been installed.

Application scenario for the publish/subscribe messaging model

When using the publish/subscribe model, many applications might be receiving request messages. If the operation being invoked is request/response (that is, has an output or fault message defined in the interface), all those applications return a response, and additional logic is required to either choose one or aggregate the responses. This is why WebSphere Process Server and WebSphere Enterprise Service Bus only support the use of one-way operations with the publish/subscribe messaging model.

A message is published under a topic for a group of interested subscribers (see Figure 11).

Figure 11. An application scenario for publish/subscribe messaging model

Figure 11 shows an application scenario for the publish/subscribe messaging model. The WSJMSPublisher application publishes a message using the greetingTopic topic. The JMS provider that owns the topic sends it to the topic's subscribers. In this example, there's only one subscriber, the WSJMSBackEndSubService application. The following sections describe how to implement this scenario.

Create an interface with one-way operation for the publish/subscribe messaging model

Create a new interface called GreetingService under MyLibrary.
Create a one-way operation: void sayHello(string message);.

You can use the automatically generated SIBus JMS resources for the point-to-point messaging model. In the publish/subscribe messaging model, you have to configure and create the publish/subscribe SIBus JMS resources from the Admin Console.

Create SIBus JMS resources for the publish/subscribe model

You need to create some SIBus JMS resources in the Node scope before installing the application:

Create a topic connection factory called greetingTopicCF by selecting JMS > Topic connection factory.
Create a topic named greetingTopic by selecting JMS > Topics.
Create an activation spec called topicJMSAS by selecting JMS > Activation specifications.

Table 1 shows the properties of the resources you need to define when you create them in the Admin Console.

Table 1. SIBus JMS resources required for the publish/subscribe messaging model

SIBus JMS resources	Topic connection factory	Topics	Activation specifications
Name	greetingTopicCF	greetingTopic	topicJMSAS
JNDI name	jms/greetingTopicCF	jms/greetingTopic	jms/topicJMSAS
Bus name	SCA.APPLICATION.hostNode01Cell

The topic connection factory is used for the publisher's Web service SOAP over JMS import binding to make a connection to the SIBus JMS provider to publish messages. The last part of the bus name, hostNode01Cell, is different from machine to machine.

For topics, you also need to provide the topic name and topic space, as shown in Figure 12. The activation specification uses the topic. You can use the default topic space there.

Figure 12. Configure a topic in the Admin Console

For the activation specifications, you also need to specify a destination type and a destination JNDI name, as shown in Figure 13.

Figure 13. Configure an activation specification in the Admin Console
Configure an activation specification in the Admin Console

Create a Web service with SOAP over JMS for subscribing a topic

A subscriber is a message consumer that receives messages under a particular topic, published by a message publisher.

In WebSphere Process Server and WebSphere Enterprise Service Bus, a module that includes an export with a Web service SOAP over JMS binding is a subscriber. The MDB that's part of the export binding implementation receives messages from a topic destination and translates them into the required form for the component it's wired to.

A module that has an import with a Web service SOAP over JMS binding is a publisher that publishes a message under the topic.

The steps to create a module, WSJMSBackEndSubService, which includes an export with a Web service SOAP over JMS binding and a Java component, are the same as described in the point-to-point messaging model. The module is shown in Figure 14.

Figure 14. Configure the export MDB properties

After creating this project, you need to build it in WebSphere Integration Developer. The build process creates some artifacts that need to be modified to use the publish/subscribe messaging model. This includes some J2EE artifacts in the module's deployment descriptor file, ejb-jar.xml, which you can find in the J2EE project. By default:

The message destination type is javax.jms.Queue.
The activation specification destination type is javax.jms.Queue.

You have to change them as shown in Figure 15:

Open the ejb-jar.xml file with the deployment descriptor editor in the EJB project. Make sure to save this file only without building the project again. This is because building a Web service with the SOAP over JMS project generates the default JMS artifacts, which are related to the message queue. If you build the project after you've made changes in the deployment descriptor, the artifacts are overwritten with the defaults.
Figure 15 shows that you need to change the message destination type and the destinationType in Activation Configuration for the WebServicesJMSRouter_BackEndSOAPJMSSubExport_GreetingServiceJmsPort.

Figure 15. An example of subscriber Web service application
You also need to change the Web service SOAP over JMS binding address property by modifying the file BackEndSOAPJMSSubExport_GreetingServiceJmsPort.wsdl. Do this by choosing MyLibrary > Web Service Ports and changing

jms:/queue?destination=jms/BackEndSOAPJMSSubExport&connectionFactory=jms/ BackEndSOAPJMSSubExportQCF&targetService=BackEndSOAPJMSSubExport_GreetingServiceJmsPort

to

jms:/topic?destination=jms/BackEndSOAPJMSSubExport&connectionFactory=jms/ BackEndSOAPJMSSubExportQCF&targetService=BackEndSOAPJMSSubExport_GreetingServiceJmsPort
Export the project as an EAR file by clicking File > Export > Business Integration > Integration Module. Then click Next to select the WSJMSBackEndSubService and provide a folder to save the WSJMSBackEndSubService.ear file.
Install the WSJMSBackEndSubService.ear file from the Admin Console, and modify the Message Driven Bean listener bindings to point to the defined activation specification JNDI, as shown in Figure 16 (see a larger version of Figure 16).

Figure 16. Modified export MDB activation specification

Invoke the Web service with SOAP over JMS for publishing a topic

A Web service module containing an import with a Web service SOAP over JMS binding can publish a message under the Greeting topic; the message is consumed by the WSJMSBackEndSubService. The example of this module is called WSJMSPublisher.

Create a new module called WSJMSPublisher.
Create an import with a Web service SOAP over JMS binding by dragging the BackEndSOAPJMSSubExport_GreetingServiceJmsPort.wsdl file from MyLibrary into the assembly diagram. Select the Import with Web Service Binding option to create the import.
Change the binding property of the import component from

jms:/topic?destination=jms/BackEndSOAPJMSSubExport&connectionFactory=jms/ BackEndSOAPJMSSubExportQCF&targetService=BackEndSOAPJMSSubExport_GreetingServiceJmsPort

to

jms:/topic?destination=jms/greetingTopic&connectionFactory=jms/ greetingTopicCF&targetService=BackEndSOAPJMSSubExport_GreetingServiceJmsPort
Save the project and deploy it from WebSphere Integration Developer to the WebSphere Process Server server.

Now you can test the WSJMSPublisher with the test client in WebSphere Integration Developer; Figure 17 shows the result (see a larger version of Figure 17).

Figure 17. Test result in publish/subscribe model

Conclusion

This article demonstrated how to build and invoke Web services using SOAP over JMS in WebSphere Integration Developer and how to install and run them in WebSphere Process Server or WebSphere Enterprise Service Bus. The Web service SOAP over JMS export binding is used to create a Web service provider, and the Web service SOAP over JMS import binding is used to create a Web service client application.

The examples in this article illustrated both the point-to-point and publish/subscribe messaging models supported by the Web services capability in WebSphere Process Server and WebSphere Enterprise Service Bus. The WebSphere Integration Developer tool provides the GUI that lets you build Web service applications simply and efficiently.

Downloads

Description	Name	Size	Download method
Applications for point-to-point messaging	WSJMSPointToPoint.zip	80KB	HTTP
Applications for publish/subscribe messaging	WSJMSPubSub.zip	49KB	HTTP

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

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=SOA and Web services, WebSphere

ArticleID=309926

ArticleTitle=Web services with SOAP over JMS in IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus, Part 1: Using the SIBus JMS provider

publish-date=05222008

author1-email=xufengli@uk.ibm.com

author1-email-cc=flanders@us.ibm.com

author2-email=Simon_Holdsworth@uk.ibm.com

author2-email-cc=flanders@us.ibm.com