Introduction

WebSphere Application Server web services and messaging

IBM WebSphere Application Server V6 (WebSphere Application Server) introduces the Service Integration Bus (SIBus) support. The SIBus enables integration between loosely-coupled applications and services. Applications connect to the SIBus and are supported using message-based and Service-Oriented Architecture. A SIBus installation can have a number of destinations. Destinations are logical addresses which can have the behavior of a service endpoint, a queue, or a topic. Most importantly, destinations are active. In other words, they can perform work on the message as it passes through that destination. This is enabled by attaching a mediation to the destination.

The SIBus supports web services by using Inbound and Outbound service definitions. These define how a destination is exposed as a SOAP endpoint, and how it talks to other SOAP endpoints. Web serviceS clients external to the SIBus can send requests to an Inbound service, and web services external to the SIBus can be invoked from within the SIBus by sending requests to an Outbound service. Web services messages in the SIBus flowing between Inbound services and Outbound services can then be routed and transformed using mediations.

The SIBus also supports a mix and match approach, where SOAP/HTTP and JMS messages are routed and mediated. For example, a message can come in as SOAP/HTTP and be sent to a JMS consumer. The mediation framework is very important in this scenario because it allows the messages to be modified to match each end of the communications.

We recommend you read the two articles on this subject listed in the Resources section: "Working with the Enterprise Service Bus and Mediations", and "Building an Enterprise Service Bus with WebSphere Application Server."

The XML language E4X

ECMAScript for XML (E4X) is an extension to the JavaScript language which adds direct support for XML. It lets you create, manipulate, and use XML directly from JavaScript without requiring the use of any other XML library or API. This makes working with XML in E4X much simpler and easier than using alternatives such as DOM. It is also a more natural programming model for most Java and script programmers than XSLT. We strongly recommend you read our previous developerWorks series referenced in Resources, "AJAX and scripting web services with E4X, Part 1: Introducing E4X."

In this paper we show you how to use E4X for SIBus mediations. We also show how, when combined with the WSMediations package sample code, this can lead to very rapid development of powerful SIBus mediation flows.

The WSMediations package

The WSMediations package provides a simple framework for making SIBus mediations easy to use. Because it uses a convention over configuration approach, the work required to set up a mediation is minimized. This feature, combined with the simplicity of E4X scripts, means new mediation flows can be created much faster than when implementing flows from scratch using Enterprise JavaBeans (EJB) and XSLT transforms.

The WSMediations package uses a single mediation EJB that gets customized for each mediation based on the destination to which it runs. Mediations are written as E4X scripts, and the scripts are stored in a WebSphere Application Server shared library. That means, instead of rebuilding and redeploying an EJB, all that is required in order to update a script is to update a JAR file in the shared library. The scripts are named the same as the destination they are associated with, which enables the single mediation EJB to automatically discover the script to run at each mediated destination without requiring any specific configuration.

While the SIBus allows two dimensions of mediation flow (flows through destinations and chains of mediation at each destination), for the purposes of simplicity, we chose to support one mediation at each destination and recommend a flow of mediations to be defined as a number of destinations.

Effectively, we are promoting a pattern of usage of the SIBus in which mediation is defined by using a set of special destinations whose only purpose is to mediate a message.

The script environment that the WSMediation framework provides extends the standard WebSphere Application Server mediations APIs to provide simplified methods for getting and setting the XML representation of a message. This enables easy access and transformation of messages using E4X. For SOAP-based web service messages from or to SIBus Inbound and Outbound service destinations, the mediation framework is able to automatically determine the new Service Data Object (SDO) format string when messages have been transformed. This makes transformations very easy to code.

You can create a new mediation in three simple steps:

1. Create a new SIBus destination.
2. Mediate it with the WSMediation EJB.
3. Add a mediation script with the same name as the destination into the scripts-shared library.

Configure WebSphere Application Server to use the WSMediations package

Before using E4X and the WSMediations, you must complete the following steps to install the WSMediations package into WebSphere:

• Install the WSMediations EAR file.
• Define the WSMediations EJB as a mediation handler.
• Create a WebSphere Application Server shared library to hold the mediation scripts.
• Add xbeans.jar and replace js.jar in the WebSphere Application Server lib directory (to provide E4X support).

These steps are described in more detail in the readme file within the ws-mediationcode.zip file that you can download from this paper.

Back to top

The CurrencyStock choreography example

Now that we've explained all the parts and have the WSMediations code installed into WebSphere Application Server, we're ready to start writing mediations. To demonstrate how to use the simplified mediations, we show you how to create a new web service from a choreography of existing services. The choreography is effectively a new service whose logic is completely provided by "gluing" together existing services. This is the same example shown in Part 2 of the "AJAX and scripting web services with E4X" series (see Resources), but this time we use the WebSphere Application Server SIBus run-time instead of Apache AXIS. If you still haven't read that article (and why not!?) then this simple service takes two existing services -- a stock quote service and a currency service -- and provides a new service -- stock quotes in your local currency.

Two SIBus Oubound services are created, one for the xMethods stockquote service, and the other for the xMethods currency exchange rate service. We then use a SIBus Inbound service to expose a new currencystock service which enables external web services clients to get stock prices adjusted by currency. In this example, SIBus mediations are used to transform the CurrencyStock request into two new requests for the xMethods StockQuote and currency conversion services, which then execute concurrently. Finally, another mediation merges the two xMethod responses into a single CurrencyStock response, which is returned to the original web services client.

Figure 2 shows this choreography configuration.

WebSphere Application Server SIBus resources used to create the CurrencyStock choreography

Configure the WebSphere Application Server resources

Create the Outbound services:

• Create the xmethods stockquote service at: http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl.
• Create the xmethods currency conversion service at: http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl.

As the Outbound service and destination names generated by default are a bit unwieldy, you should change the default service and destination names to xmethodsStockquote and xmethodsCurrency when defining the Outbound service in the Name the outbound service and destinations panel.

Create the mediation destinations:

• CurrencyStockIBS
• StockquoteXForm
• CurrencyXForm
• CurrencyReply
• MergeReplies

Attach the WSMediation to all of those destinations except for the CurrencyReply destination.

Define a SIBus InboundService for the new CurrencyStock service:

• Use the CurrencyStockIBS destination and the CurrencyStockquote.wsdl supplied in the downloadable zip file ws-mediationcode.zip

The resulting WebSphere Application Server destinations should look like the wsadmin panel shown in Figure 3.

The final piece of configuration is to set the forward and reverse routing paths on some of the new destinations:

• CurrencyStockIBS frp=:StockquoteXForm replyDest=MergeReplies replyBus=dWESB
• StockquoteXForm frp=:xmethodsStockquote
• CurrencyXForm frp=:xmethodsCurrency replyDest=CurrencyReply replyBus=dWESB

Figure 4 shows the wsadmin panel showing how to configure the routing paths on a destination.

Back to top

The mediation E4X scripts

Now all that is left to do is to create the mediation scripts and add them to the scripts shared library.

Listing 1 shows the mediation script that is associated with the CurrencyStockIBS destination. Line 3 makes a copy of the current message, line 4 sends that copy to the CurrencyXForm destination, and returning true on line 6 means that the current message will continue on to the next destination in the forward routing path (the StockquoteXForm destination).

This copy script has the CurrencyXForm destination name hardcoded in it. An improvement would be to use a destination context property to define the copy-to destinations. The WSMediations framework provides methods giving scripts easy access to destination context properties (for example, the getDestinationProperty(key) method on the MessageContext). By using these methods you could write a general purpose mediation that copies a message to one or many other destinations based on the context property settings. However, we use this simple hardcoding approach in order to keep the example simple.

 1.  function process(mc) {
 2.  
 3.    var msg = mc.getSIMessage().clone();
 4.    mc.send(msg,"CurrencyXForm");
 5.  
 6.    return true;
 7.  }

Listing 2 shows the mediation script that is associated with the StockquoteXForm destination. This script converts from a CurrencyStock request into an xMethod StockQuote request, and it shows how simple and clear an XML programming language like E4X makes working with SOAP messages.

Line 3 and 4 extract the share symbol from the CurrencyStock SOAP request. Lines 6 to 14 create a new SOAP envelope suitable for the xMethods StockQuote service. This is simply a copy-and-paste from an example SOAP message from the xMethods web site. Line 11 uses the E4X curly brackets {} syntax to insert the share symbol extracted on line 4 into the envelope.

Line 16 sets the new envelope as the payload on the message. Using the reformatPayload method tells the WSMediations framework that the structure of the SOAP envelope has been changed and therefore the SDO format string needs to be recalculated. See the sidebar describing SIBus message format strings.

The CurrencyXForm script is not shown here as it is almost the same as the StockquoteXForm script -- only the SOAP message is changed to match the xMethods currency conversion service.

 1.  function process(mc) {
 2.  
 3.     var origReq = mc.getPayload();
 4.     var symbol = origReq..*::symbol.toString();
 5.     
 6.     var envelope = 
 7.        <s:Envelope xmlns:sq="urn:xmethods-delayed-quotes" 
 8.                    xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
 9.           <s:Body>
10.              <sq:getQuote>
11.                 <symbol>{symbol}</symbol>
12.              </sq:getQuote>
13.           </s:Body>
14.        </s:Envelope>
15.  
16.     mc.reformatPayload(envelope);
17.     
18.     return true;
19.  }

Listing 3 shows the mediation script that is associated with the MergeReplies destination. This script receives the responses from StockQuote and currency services, extracts the returned values, and constructs a CurrencyStock response SOAP message. This mostly works in a very similar way to what has already been described for the StockquoteXForm script, with the additional function on lines 6 and 7, which receive the currency response message from the CurrencyReply destination. This works by using the correlation ID of the response message and probably needs a little more explanation:

A SIBus message has two IDs -- a message ID and a correlation ID. When the Outbound service is invoked, the SIBus service invoker sets the correlation ID on the response message to the same value as the message ID of the request message. This enables the request and response messages to be linked together. As the copy script on the CurrencystockIBS destination clones the request message, the resulting two request messages both have the same message ID. This means that now when the MergeReplies script is trying to receive the currency response message, it can use the correlation ID from the StockQuote response, because the StockQuote and currency requests both used the same message ID.

 1.  function process(mc) {
 2.  
 3.     var stockquoteEnvelope = mc.getPayload();
 4.     var ticker = stockquoteEnvelope..*::Result.toString();
 5.     
 6.     var correlationID = mc.getCorrelationID();
 7.     var currencyEnvelope = mc.receiveXML("CurrencyReply", correlationID);
 8.     var rate = currencyEnvelope..*::Result.toString();
 9.  
10.     var envelope = 
11.        <s:Envelope xmlns:cs="http://sample" 
12.                    xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
13.           <s:Body>
14.              <cs:getQuoteResponse>
15.                 <getQuoteReturn>{rate*ticker}</getQuoteReturn>
16.              </cs:getQuoteResponse>
17.           </s:Body>
18.        </s:Envelope>
19.  
20.     mc.reformatPayload("CurrentcyStockIBS", envelope);
21.  
22.     return true;
23.  }

Back to top

Test the new CurrencyStock web service

That's it! You can now test the new CurrencyStock service from any web services client. In the sample download you can find a simple HTML page that uses E4X, so it requires the latest developer version of Mozilla to run. Alternatively, you could use the web services explorer utility provided with IBM Rational® Application Developer, or use your favorite web services tool to create a web services client from the currencystock.wsdl.

Figure 6 shows an example of the E4X Mozilla client and the result of requesting the IBM share price in my homeland currency. You can get a list of the currencies that the xMethods currency exchange rate service supports from its help page (see Resources).

Back to top

Conclusion

In this paper, the authors showed you how you can use the combination of a simple framework (WSMediation) together with a lightweight XML scripting language (E4X) to do simple and powerful web services routing and mediation. The power and ease of this approach makes building ESBs around WebSphere Application Server V6 faster and more productive.

Back to top

Download

Information about download methods

Resources

• Read more about E4X in the paper "AJAX and scripting web services with E4X, Part 1: Introducing E4X" (developerWorks, April 2005).
  
  
• Get a further introduction to E4X in the paper "AJAX and scripting web services with E4X, Part 2: Create new web services with E4X" (developerWorks, April 2005).
  
  
• Learn how to use WebSphere mediations from "Working with the Enterprise Service Bus and Mediations" (developerWorks, February 2005).
  
  
• Learn how to use the new messaging engine in IBM WebSphere Application Server V6 to build an Enterprise Service Bus, a crucial piece of SOA infrastructure, in the paper "Building an Enterprise Service Bus with WebSphere Application Server" (developerWorks, January 2005).
  
  
• Get a list of the currencies that the xMethods currency exchange rate service supports from its help page.
  
  
• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  
• Browse for books on these and other technical topics.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Want more? The developerWorks SOA and web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop web services applications.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• The CurrencyStock choreography example
• The mediation E4X scripts
• Test the new CurrencyStock web service
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers