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

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.

Share:

Fenglian Xu, Software Engineer, IBM

Dr. Fenglian Xu photoDr. 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 HoldsworthSimon 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.



22 May 2008

Also available in Chinese

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
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:

  1. 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.
  2. 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
    An example of BO with five fields
  3. To create an interface called in MyLibrary, right-click Interface > New, and enter CustomerService as the name in the wizard. Click Finish.
  4. 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
    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:

  1. Create a new module clicking File > New Module and entering WSJMSBackEndService as the module name in the wizard. Click Finish.
  2. Create a SOAP over JMS export by dragging the Export icon export icon into the assembly diagram and generating a Web service SOAP over JMS binding with the default settings.
  3. Create a Java component called HandleRequest with the interface CustomerService.
  4. Wire up the BackEndSOAPJMSExport and the HandleRequest component, as shown in Figure 4.
    Figure 4. WSJMSBackEndService application
    WS JMS Back End Service application
  5. 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.

  6. 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
    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:

  1. Export the WSJMSBackEndService project into an .ear file, WSJMSBackEndService.ear, and install it from the Admin Console.
  2. 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
Activation specification created for the export MDB
Figure 7. JNDI resources for both request and response connection factories
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:

  1. Create a new module called WSJMSMessageSender.
  2. Navigate to BackEndSOAPJMSExport_CustimerServiceJmsPort under MyLibrary in the business integration perspective.
  3. Drag the BackEndSOAPJMSExport _CustomerServiceJmsPort and drop it into the assembly diagram.
  4. 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
    Example of creating the MessageSender application
  5. 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
    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:

  1. Start the server from WebSphere Integration Developer.
  2. Add the WSJMSMessageSender project to the server.
  3. Right-click WSJMSMessageSender to test the module.
  4. Select an operation to test, such as getCustomerInfo, and enter the value for the ID parameter.
  5. 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
    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
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

  1. Create a new interface called GreetingService under MyLibrary.
  2. 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:

  1. Create a topic connection factory called greetingTopicCF by selecting JMS > Topic connection factory.
  2. Create a topic named greetingTopic by selecting JMS > Topics.
  3. 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 resourcesTopic connection factoryTopicsActivation specifications
NamegreetingTopicCFgreetingTopictopicJMSAS
JNDI namejms/greetingTopicCFjms/greetingTopicjms/topicJMSAS
Bus nameSCA.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
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
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:

  1. 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.
  2. 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
    An example of subscriber Web Service application
  3. 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
  4. 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.
  5. 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
    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.

  1. Create a new module called WSJMSPublisher.
  2. 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.
  3. 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
  4. 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
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

DescriptionNameSize
Applications for point-to-point messagingWSJMSPointToPoint.zip80KB
Applications for publish/subscribe messagingWSJMSPubSub.zip49KB

Resources

Learn

Get products and technologies

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

Discuss

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 SOA and web services on developerWorks


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