IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 5

Switching protocols

As promised in Part 4, we are now ready to look at a scenario where the Enterprise Service Bus (ESB) helps mediate between different protocols for the service requester and the service provider. We will build on top of the examples provided in the previous articles in this series, basically adding new "virtual" services that support a variety of protocols, all supporting the notion of the ESB enabling the connection of any requester with any provider.


Andre Tost, Senior Technical Staff Member, IBM

Andre TostAndre Tost works as a Senior Technical Staff Member in the Software Group's Enterprise Integration Solutions organization, where he helps IBM's customers establishing Service-Oriented Architectures. His special focus is on Web services technology. Before his current assignment, he spent ten years in various partner enablement, development and architecture roles in IBM software development, most recently for the WebSphere Business Development group.

Rachel Reinitz (, Distinguished Engineer, IBM

Rachel ReinitzRachel Reinitz is an IBM Distinguished Engineer with IBM Software Services for WebSphere and a member of the IBM Academy of Technology. She has built much of IBM’s internal and external intellectual capital and education on SOA, Enterprise Service Bus, and Web services. Rachel focuses on how to get started with SOA and ESB best practices. She consults with clients and ISVs on how SOA and ESB can be used to achieve their business and technical objectives. She is a frequent conference presenter and written many developerWorks articles on ESB and Web services. Rachel lives in the Bay Area in California, and enjoys hiking, socializing, and international travel.

09 May 2007

Also available in Chinese

From the IBM WebSphere Developer Technical Journal.


An Enterprise Service Bus (ESB) supports interactions across a number of transport and message protocols. In that respect, IBM® WebSphere® ESB is no different. In previous articles in this series, we have described and shown examples for the exchange of messages across WebSphere MQ, JMS, and SOAP over HTTP. Here, we will take the next step and show how WebSphere ESB supports a key principle of the Enterprise Service Bus pattern, namely that of "virtualized" services.

Offering a virtual service means hiding the actual location, protocol, and even the exact interface of a service provider from the service requester. With examples, this article illustrates how you can offer a service to a requester in a different protocol than the service provider expects. In fact, we will offer the same services over two protocols at the same time, thus exposing it to a variety of consumers. What you will see is that this does not actually require a lot of extra work when using WebSphere ESB because of its underlying Service Component Architecture (SCA).

This article will follow the same outline as earlier articles, first by starting out with the business scenario, then describing the architecture of the solution, and finally explaining how to make it all work (including testing it) in WebSphere ESB.

Enhanced scenarios

We will reuse two of the earlier scenarios of our fictional Posts-R-Us company.

In the first scenario, we had described how each time a package is received, a message is sent to a backend application so that the status of the order is updated accordingly. In Part 2, we showed how the message is sent to the ESB through a JMS queue, and then forwarded (again using JMS) to the backend application, which receives the message through a message-driven bean. We then enhanced that setup in Part 4, adding a new outbound WebSphere MQ channel. Now, finally, we will enhance it yet again by adding client access via a Web service using SOAP/HTTP, as shown in Figure 1.

Figure 1. Adding a new channel to send "package received" events (Scenario 1)
Figure 1. Adding a new channel to send

Through this enhancement, the event indicating that a package was received by a customer can be sent from two different types of client: one using an asynchronous protocol, the other a synchronous protocol. The backend application is not affected by this at all, since the ESB provides the virtual service interface to the clients.

The second scenario, which was covered in Part 3, provided a service with which customers and employees could track the status of an individual package. The service was implemented as a regular Web service over SOAP/HTTP. The requester in our example also used SOAP/HTTP as the protocol (in fact, you utilized the Web Services Explorer tool in IBM WebSphere Integration Developer to run the scenario). Here, you will add access to this service through a pair of WebSphere MQ queues, which will offer the service for use from applications that can easily communicate with WebSphere MQ, but don't have any support for Web services.

Figure 2. Adding a new channel to receive package status (Scenario 2)
Figure 2. Adding a new channel to receive package status (Scenario 2)

Again, the existing service is not affected by this additional consumer; the details of the new protocol are completely handled by the ESB.

Scenario 1: Add a SOAP/HTTP consumer to a JMS service

If you don't want to walk through the steps described here, the completed solution is available in the download file included with this article, in a Project Interchange file called

  1. Begin by importing the PackageReceivedPart4.ear file into WebSphere Integration Developer. This EAR file (and other files you will need) are contained within the file, available in the download section. The EAR file can also be found in the materials you downloaded in Part 4; you won't be changing the application at all. Remember that this is an application with a message-driven bean that receives messages over a JMS queue and prints their content to the screen. After creating the example in Part 2, you will have added another import with MQ bindings to it in Part 4. Don't add the resulting project to the runtime environment yet.

  2. Import the project interchange file, which includes the mediation module you will use. It is called, and again, you can retrieve it from the download section of this article or find it with Part 4.

  3. Open the Business Integration perspective and load the module into the Assembly Editor, which should look like Figure 3.

    Figure 3. The unchanged mediation module assembly
    Figure 3. The unchanged mediation module assembly

    To make the mediation accessible to a Web services client via SOAP over HTTP, you simply add another export and give it the appropriate bindings. That's the beauty of the SCA assembly model: you don't have to change the actual mediation flow component at all; you can "wire" an additional export to it.

  4. In the Assembly Editor, drag an Export from the palette and drop it on the canvas, rename it to SOAPClientExport, and connect it to the mediation flow component. This will also add the appropriate interface to the export. Right-click on the export and select Generate Binding... => Web Service Binding, as shown in Figure 4.

    Figure 4. Generate Web Service Binding
    Figure 4. Generate Web Service Binding
  5. In the next dialog, select soap/http as the transport.

  6. Save your changes. Done!

  7. Before you can deploy and test the updated module, you need to add an activation spec to the server, since that is what the receiving message-driven bean uses to connect to the proper JMS queue. All of this is described in detail in Part 2 (and you may still have it configured if you have been following this series), but here's a brief summary:

    1. Start the WebSphere ESB test server.
    2. Once it is started, run the admin console for the server by right-clicking on the server and selecting Run administrative console.
    3. In the console, navigate to Resources => JMS Providers => Default messaging.
    4. Select JMS activation specification.
    5. Create a new activation specification with these values:
      • Name: PackageReceivedActivationSpec
      • JNDI name: eis/PackageReceivedActivationSpec
      • Destination JNDI name: PackageReceivedModule/MDBImport_SEND_D
      • Bus name: SCA.APPLICATION.esbCell.bus
    6. Save your changes and restart the server.
  8. To run the JMS test client, you would have to create a few more artifacts; we won't do that here, because we are focusing on the Web services export channel. For detailed information on how to deploy and run the JMS test client, see Part 2; none of that has changed at all in our updated scenario. Also, as mentioned earlier, the module we are using includes a WebSphere MQ import. This will cause the received message to be forwarded to an MQ queue called PackageReceivedQueue. We created the import, as well as the associated queue in Part 4.

  9. Once your server is started again, you can add the PackageReceivedModuleApp and PackageReceivedPart4 projects to the server. Make sure you select the module first, since its deployment will generate the queues and other definitions that are used by the message-driven bean.

    You can test the new Web service export simply by right-clicking on the SOAPClientExport_PackageReceivedIFHttp_Service.wsdl in the J2EE perspective and selecting Web Services => Test with Web Services Explorer. Once you run the test, it should look like Figure 5.

    Figure 5. Testing scenario 1
    Figure 5. Testing scenario 1

Scenario 2: Adding a WebSphere MQ consumer to a SOAP/HTTP Web service

Let's switch to our second scenario, which covers a request-response type of service. The service provider offers this service via SOAP over HTTP, and the mediation module (which you built in Part 3) also exposes it over this protocol. You will now add access over WebSphere MQ to this service, essentially opening it up to an asynchronous protocol, even though the service operation itself is implemented synchronously. Figure 2 showed what the updated architecture of the solution looks like.

To build this solution:

  1. Start by importing the backend service provider application, which you can find in the downloaded PackageStatusNewEAR.ear file. There is nothing exciting about this application, it simply prints out messages received and returns a default response message. You will deploy this application later on the test server.

  2. Import the mediation module that is associated with the service, which you can find in the project interchange file. (As before, you can alternatively find the already completed solution in the downloaded file.)

  3. Once you have imported the PackageStatusModule module, open it in the Assembly Editor in the Business Integration perspective. The assembly should like Figure 6.

    Figure 6. The PackageStatusModule assembly
    Figure 6. The PackageStatusModule assembly
  4. Before you can add the additional export for WebSphere MQ access, take a look at an interesting detail in the service interface for the module or, more specifically, in the schema it contains. Open the PackageTrackingService interface with the WSDL editor (instead of the default Interface Editor) by right-clicking on the file and selecting the Open With => WSDL Editor menu option (Figure 7).

    Figure 7. Opening the service interface with the WSDL Editor
    Figure 7. Opening the service interface with the WSDL Editor
  5. Double-click on the http://service.postrus namespace in the Types section (this assumes you selected the Graph tab on the editor window). The elements and types that are defined for this interface will display (Figure 8).

    Figure 8. Global elements in the service interface
    Figure 8. Global elements in the service interface

    There are two global elements in there that would normally not be required in a plain Web service scenario, namely PackageIdentifier and PackageStatus. Looking at the source, these two elements are defined as follows:

    <element name="PackageIdentifier" type="impl:PackageIdentifier"/>
    	<element name="PackageStatus" type="impl:PackageStatus"/>

    For your WebSphere MQ bindings, you will want to use those two global elements (which are named after the types they "wrap"), rather than the other two global elements, which are used in a SOAP/HTTP scenario.

  6. You are now ready to add the new export. Open the module assembly in the Assembly Editor and add a new export to the canvas. Rename it to PackageStatusExportMQ, and connect it to the mediation module, which will also add the appropriate interface to the export.

  7. Right-click on the new export and select Generate Binding... => Message Binding... => MQ Binding.

    Figure 9. Adding MQ binding to the export
    Figure 9. Adding MQ binding to the export
  8. In the resulting dialog, you need to specify the WebSphere MQ parameters that you want to use for the exchange. The values here will depend somewhat on your local MQ installation, but they should basically be like this (fields not listed here can retain their default values):

    • Request Queue Manager: [this is your default queue manager]
    • Receive Destination Queue: PackageStatusRequestQueue
    • Send Destination Queue: PackageStatusResponseQueue
    • Host Name: localhost
    • Request Serialization Type: Serialized as XML
    • Response Serialization Type: Serialized as XML
    Figure 10. Defining MQ binding properties
    Figure 10. Defining MQ binding properties

    All of these values can also be changed later in the Properties view. Click OK and save your changes.

  9. You won't be making any changes to the mediation flow component implementation in this example, but feel free to open the component in the Mediation Flow Editor to see what the mediation actually does. Notice that it logs both request and response messages. Moreover, the response flow contains a custom mediation that prints out the response message. The code within this custom mediation looks like this: serializer = 
    	INSTANCE.locateService("com/ibm/websphere/bo/BOXMLSerializer"); baos = new;
    try {
      serializer.writeDataObject(input1, "http://service.postrus", 
    	"getPackageStatus", baos);
    } catch ( x) {}	
    System.out.println(new String(baos.toByteArray()));
    return input1;

    This is very generic code that you can reuse for other types of mediations, too, given that you change the namespace and root message values, respectively.

  10. Before you can deploy this updated module, you need to create the queues that we specified in Figure 9. Open the WebSphere MQ Explorer, and create two new local queues under the queue manager that you already defined. Name them PackageStatusRequestQueue and PackageStatusReponseQueue. There is nothing special required for these queues, so you can use all default values for them.

  11. Switch back to WebSphere Integration Developer, but leave the MQ Explorer window open because you will need it later for testing. You can now deploy your module and service provider to the test server. Start the server, then once started, add the PackageStatusServiceNewEAR and PackageStatusModuleApp projects.

    (These instructions assume that the test server you use is running on port 9081, which is the default for the WebSphere ESB test server. If you are using a different port, you must update the port definitions for both the module and the actual service in the PackageStatusModule project, as well as in the properties for the PackagesStatusServiceImport.)

  12. You are now ready to send a test MQ message to the mediation, see how it gets logged and forwarded to the service provider over SOAP/HTTP, and see how the response is routed back to the response MQ queue. Use MQ Explorer to send the test message. Right-click on PackageStatusRequestQueue and select the Put Test Message... option.

    Figure 11. Putting a test messge to the MQ request queue
    Figure 11. Putting a test messge to the MQ request queue

    The message you want to send to the mediation looks like this:

    <p:PackageIdentifier xmlns:p="http://service.postrus">

    Notice how the root element of this message is equal to the global element definition we looked at earlier in the service interface file.

    Figure 12. The test message
    Figure 12. The test message

    If the test runs successfully, output will appear in the server console, and the response message will appear in the PackageStatusResponseQueue. You can view it there again using the MQ Explorer tool.

    Figure 13. Browsing the response message
    Figure 13. Browsing the response message
    Figure 14. The response message
    Figure 14. The response message

    Figure 14 shows what the response message entry looks like. The expected response message is this:

    <?xml version="1.0" encoding="UTF-8"?>
    <service:PackageStatus xmlns:service="http://service.postrus">

    Again, notice how the root element of the response message is the global element that is named after the contained complex type.

To compare this scenario and message ouput to the Web services export, you can simply use the Web Services Explorer tool in WebSphere Integration Developer to send a test SOAP message to the mediation. Even though the message formats for request and response are different when they appear at the respective export, they will be identical as soon as they hit the mediation flow component. Additional exports with different bindings can be added in the same way.


In this article, showed how enabling additional protocols for use by service providers and consumers is really very simple using the import/export wiring approach in WebSphere ESB and its underlying Service Component Architecture. You can expose an existing service provider that was developed for use with JMS to consumers that only support SOAP over HTTP. Similarly, you can add support for WebSphere MQ-based consumers to SOAP/HTTP-based service providers. Best of all, none of these changes require any update of the service logic or the mediation flow logic! The fact that all messages are converted to and from the Service Message Object format in WebSphere ESB enables manipulating and processing those messages without regard to the protocol that is used to receive or send them.

As in our previous series about Enterprise Service Bus implementations using WebSphere Application Server, this concludes our description of basic ESB capabilities in WebSphere ESB. There are many more details and more interesting scenarios to cover, but we will leave that to future articles. In our next, and final, installment, we will provide you with a summary of what we have covered. and offer an outlook into what you can expect in the future, in terms of both articles and in how the product will evolve further.

More in this series


Code samplepart5downloads.zip122 KB



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 Business process management on developerWorks

Zone=Business process management, WebSphere, Architecture
ArticleTitle=IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 5