 | Level: Intermediate Chris Whyley (whyleyc@uk.ibm.com), Software Test Engineer, IBM Hursley Software Laboratory
14 Jul 2006 This article is the second in a two-part series that explores the powerful Web services message manipulation features of the Service Integration Bus (SIBus), a key technology within IBM WebSphere® Application Server V6. Here in Part 2, we focus on the mediations programming model as a mechanism for SIBus users to manipulate in-flight Web services messages. After an introduction to this relatively new technology we examine when to use mediations, and look in greater detail at how to code, then deploy a sample mediation to work with messages sent or received from target Web services. Finally, we offer coding recommendations for writing mediations to perform more advanced Web service message manipulation tasks.
Introduction
The first article in this series provided an overview of the SIBus, and the benefits it offers when tying together a Web services infrastructure. It detailed the options for intercepting and accessing Web services messages being transported across the bus, and included an in-depth look at the use of JAX-RPC Handlers as a mechanism for accessing and working with such messages.
This second article examines the mediations programming model as an alternative to JAX-RPC Handlers, to manipulate Web services messages being passed through the SIBus. Mediations are a new concept in WebSphere® Application Server V6 and, like JAX-RPC Handlers, they provide a way for application developers to manipulate runtime message content. Unlike JAX-RPC Handlers, however, they are not limited to manipulation of SOAP messages, but can handle any message represented in the Service Data Object (SDO) format. For more information on SDO see the Resources section of this article.
Before you continue, we recommend you read and understand Dan Murphy's article "The basics of message mediation" (developerWorks, March, 2005) to understand the mediations programming model and see how mediations can be used to manipulate JMS message content within the SIBus. Dan focuses on mediations and JMS messages. This article concentrates on their application to Web services messages. However, many of the basic concepts in Dan's article apply, and we assume here that you are familiar with the concepts behind developing, deploying, and testing a simple mediation handler.
Preparation
To develop and test the mediations contained in this article, ensure that you have followed the steps from "Create a Simple HTTP Web Services Gateway Service with WebSphere Application Server V6" (developerWorks, July 2005) which describes how to set up and call a sample Web service through the service integration bus. The development and deployment steps described there and in this article can be used with any of the following IBM products:
- IBM WebSphere Application Server Toolkit Version 6.0 and WebSphere Application Server V6
- IBM Rational® Application Developer V6, including the integrated WebSphere Application Server V6 test environment
- IBM Rational Application Developer V6 and WebSphere Application Server V6
- IBM Rational Software Architect V6.0, including the integrated WebSphere Application Server V6 test environment
You should download and apply the latest service levels for the products you install. At the time of publication, WebSphere Application Server V6 Refresh Pack 2 (V6.0.2) is the latest fixpack. You can use the Rational Product Updater to get updates to the Rational products. It is installed automatically when you install the any Rational products. Alternatively, you can manually download fixpacks from the IBM Rational Support Web site.
Why use mediations ?
Before heading down the route of mediation development it is worth considering whether the technology is the best fit for your environment. As we have seen in Part 1 of this series, JAX-RPC Handlers provide a convenient and lightweight way to manipulate web services messages with a number of advantages. Mediations on the other hand are a more "heavyweight" technology option. Developed and deployed as stateless session Enterprise Java Beans (EJB's) they can only be used within the server container and require knowledge of the Service Data Object (SDO) programming API in order to use. They do however offer a number of advantages over JAX-RPC Handlers:
- Common access to JMS and SOAP messages
- Message format transformation
- The ability to re-route messages
- Options for message cloning and distribution
Let's look at each of these areas in more detail:
(1) Common access to JMS and SOAP messages
If you operate in an environment where you need access to both SOAP and JMS messages, mediations are an excellent choice. They provide a common programming model (SDO) for dealing with both types of message. The fact that the API remains common across message types encourages code reuse even in environments where the message types are completely different. It also provides a lower barrier for developers who may be moving between the two technologies -- mediations enable them to have a consistent interface into message manipulation.
Figure 1 gives a simple example of how you can use the same mediation to process messages from both Web services and JMS clients, no matter what type of consumer is picking up that message. Common Java code could be used here to perform say simple logging or message inspection.
Figure 1. High level mediations overview
(2) Message format transformation
Mediations provide a convenient and powerful method for transforming messages from one format to another in a way that is transparent to the end-user application. For example, it is possible to send a message to a destination on your bus over SOAP/HTTP and insert a mediation into the flow to capture the incoming message, clone it, convert the clone to a JMS format and forward that message on to a JMS queue.
(3) The ability to re-route messages
Every message that is sent to a destination in the service integration bus has a routing path value associated with it, giving details of where the message is headed (see the section on a mediation's view of a message for more details). A powerful feature offered by mediations is the ability to modify this value and route the message to a different destination. This can be useful if you develop an application that needs to perform some kind of conditional routing. Say, for example, you have a Web service that offers different levels of service to customers: gold, silver and bronze. In this case you could use a mediation to inspect the incoming message, determine what service level a customer is signed up to and route the message to the appropriate web service destination in the bus.
(4) Options for message cloning and distribution
Another advantage mediations have over JAX-RPC Handlers is their ability to clone exact copies of messages. This can be useful if you have an auditing requirement to capture exact copies of messages flowing through your bus. Cloned messages can be manipulated in the same way as normal messages, meaning that they can, for instance, be routed on to other destinations for further processing.
A mediation's view of a message
A mediation's view of an incoming SOAP message is different than that of a JAX-RPC Handler, and it's worth spending a few moments considering the differences. Any messages flowing across a service integration bus, whether SOAP or JMS, are treated as Service Data Object (SDO) messages; SDO is a data programming specification, agreed upon by IBM and BEA in late 2003, that allows you to manage messages in a protocol independent way. For a detailed guide to SDO see "Introduction to Service Data Objects" (developerWorks, 2004). A set of Java APIs exist for accessing SDO messages, and you can use them your mediation to access the underlying SOAP message contents. Figure 2 highlights the three main aspects common to any SDO message arriving at a mediation:
- Message header
This part of the message comprises certain properties relating to the incoming message. All messages will have reverse and forward routing path properties that detail a list of destinations on the bus that the message will pass through on the way to its ultimate destination ("forward") and then back again from that destination ("reverse") if it is a request/response style message. Both of these properties can be queried and modified in a mediation, to give you complete control over the path that an SDO message takes through your bus. This can be useful if you need to perform some kind of conditional formatting based, for example, on the contents of SOAP messages flowing across a destination to which your mediation is attached (maybe your bus offers varying levels of Web service quality based on user provided authentication information in the SOAP message).
The message header can also contain message reliability, priority and correlation ID properties (if the message is a JMS message). In a Web services world it can be useful to access and modify this data if you are dealing with SOAP/JMS messages.
- Message context
When you create a destination on a service integration bus it's possible to use the administration console to set extra properties on it in the form of name/value pairs. A mediation attached to that destination can read these values using the message context part of the incoming message. Such extra properties can be useful if you want to pass values dynamically into your message at runtime. You can set different values on a per-destination basis, and your mediation can read and act upon them, enabling you to route or transform the message accordingly.
- Message payload (SDO datagraph)
The content of a message arriving at a mediation is stored in an SDO Datagraph. A DataGraph object represents data in a tree-like structure, with a root object at the top of the tree and children under it, similar to the structure that you might find in an XML document. A set of Java APIs exist for accessing and modifying this DataGraph and this is what mediations are able to use to inspect and manipulate the message content. Most of the remainder of this article will focus on how we program mediations to access this content when the incoming message is a SOAP message.
Figure 2. A mediation's view of a message
Write a mediation to access SOAP messages
Having covered the theory of using mediations to access Web services message content, it's time to move on to practice. In this section we'll code a simple mediation to print out the contents of an incoming SOAP message. The function is similar to the JAX-RPC Handler we coded in Listing 1 of Part 1 of this series. We will simply print out the contents of the SOAP message to the WebSphere SystemOut logfile. Such a mediation is useful for debugging problems within a Web services application, or for logging messages that pass through your service integration bus.
Note 1: We will refer to Dan Murphy's article "A practical introduction to message mediation" throughout this section. He provides comprehensive instructions on how to use Rational Application Developer to develop and package your mediation, and it is worth familiarizing yourself with that article before continuing.
Note 2: All of the code for your mediation can be copied from the listings provided in this article. However, if you want to download the finished mediation in its entirety then skip ahead to the Downloads section.
- Create a mediation handler project
Mediations are simply Java classes, packaged in Enterprise Application Archive (EAR) files that implement the mediation handler interface. To create our Web services debugger mediation, start by following the first two steps in the A practical introduction to message mediation (Step 1. Create a mediation handler project and Step 2. Create the mediation handler, but don't add any of the code mentioned in the article). Use the following naming conventions:
Project name: WebServicesMediation
Mediation class name: WebServicesDebugMediation
This will give you a basic mediation handler class that we can now begin to populate with function to debug incoming Web services messages.
- Write the code for your mediation
Now that we have a skeleton class for our mediation we can begin to populate it with code, starting with a package and some import statements that we will make use of later (see Listing 1 below):
Listing 1. Add package and import statements
package mediation.handlers;
import java.util.Iterator;
import java.util.List;
import javax.xml.rpc.handler.MessageContext;
import com.ibm.websphere.sib.SIMessage;
import com.ibm.websphere.sib.exception.SIDataGraphFormatMismatchException;
import com.ibm.websphere.sib.exception.SIDataGraphSchemaNotFoundException;
import com.ibm.websphere.sib.exception.SIMessageDomainNotSupportedException;
import com.ibm.websphere.sib.exception.SIMessageException;
import com.ibm.websphere.sib.mediation.handler.MediationHandler;
import com.ibm.websphere.sib.mediation.handler.MessageContextException;
import com.ibm.websphere.sib.mediation.messagecontext.SIMessageContext;
import commonj.sdo.DataGraph;
import commonj.sdo.DataObject;
import commonj.sdo.Property;
|
The key to any mediation is the handle() method, which is automatically invoked whenever a message is passed to your mediation. This method is analogous to the handleRequest method found in JAX-RPC handlers, and like that method is passed a javax.xml.rpc.handler.MessageContext object representing the in-flight message. In the mediations world this MessageContext is actually extended by the SIMessageContext interface, to enable finer-grained control over the incoming message. It is this SIMessageContext that we can use to access message properties, mediation session facilities and the message body itself.
To add basic functionality to your mediation, copy and paste the code in Listing 2 below to the handle() method of your mediation. This code extracts the SDO datagraph from the SIMessageContext object,
prints out some debug statements and then calls the printNodeData() method -- which we will cover shortly -- to print basic message information to System Out. Don't forget to modify the variable name for MessageContext in the handle()
method signature.
Listing 2. Fill in implementation for the handle() method
public boolean handle(MessageContext msgCtx) throws MessageContextException {
recordInLog("Mediation starting");
// Define and initialise variables
boolean continueProcessing = true;
SIMessageContext siContext = (SIMessageContext) msgCtx;
SIMessage msg = siContext.getSIMessage();
// Process the message
try {
// Get the SDO datagraph
DataGraph graph = msg.getDataGraph();
// Get the Root and Info nodes from the datagraph
DataObject rootNode = graph.getRootObject();
DataObject infoNode = rootNode.getDataObject("Info");
// Record that we have an incoming msg,
//and call the printNodeData() method to print message details
recordInLog("------------------------------");
recordInLog("Incoming Web services message:");
recordInLog("------------------------------");
printNodeData(infoNode, "");
recordInLog("------------------------------");
} catch (Exception e) {
// If we have an exception we don't want
// to continue processing the msg in other mediations
continueProcessing = false;
e.printStackTrace();
}
// If everything is ok we can continue processing the message
return continueProcessing;
}
|
To complete our mediation we need to add two more helper methods to our class. The recordInLog() method is just a simple one line method that prints a string message to System Out having prepended the class name to the message, which
is useful for keeping track of which what class is writing to the logfile, especially if we have multiple mediations in our environment. The printNodeData() method meanwhile takes the dataObject we extracted from the SDO datagraph and
examines it to pull out some key data from the message, including the name of the operation being called and the payload of the incoming message. To add these methods just copy the code from Listing 3 below into
your WebServicesDebugMediation class.
Listing 3. Add helper methods
private void recordInLog(String msg) {
System.out.println("*** " + this.getClass().getName() + ": " + msg);
}
private void printNodeData(DataObject dataObj, String indent) {
// Get the message body node from the Info node
DataObject body = dataObj.getDataObject("body");
// Print out basic msg info
recordInLog("OperationName = " + dataObj.getString("operationName"));
recordInLog("MessageName = " + dataObj.getString("messageName"));
// Get the parameters passed in
DataObject params = body.getDataObject("parameters");
// Get the string value from the input parameter
String paramValue = params.getString("s");
// And log it
recordInLog("Parameter value = " + paramValue);
}
|
- Assemble your mediation into an Enterprise Application
Having written the code for our mediation we now need to export the mediation from our workspace for use in WebSphere Application Server. To do this we can again follow the steps used in "A practical introduction to message mediation" (Step 8. Create an enterprise application project, Step 9. Set the EJB JAR dependency, and Step 10. Add the mediation handler to the EJB deployment descriptor). Use the
following naming conventions:
Mediation handler name: WebServicesDebugMediationHandler
After you have saved your modified EJB deployment descriptor you then need to export your Enterprise Application to your filesystem (for later deployment to WebSphere Application Server). To do this from within Rational Application Developer, click on File >
Export > EAR file > Next and select DeployableMediation as your EAR project. Hit the browse button and select a folder to save you EAR to (save it as DeployableMediation.ear).
Figure 3 gives an example of exporting your EAR file.
Figure 3. Exporting a mediation EAR file from Rational Application Developer
 |
Deploying mediations to the bus
Note: As a prerequisite for using your mediation, ensure you have completed the steps in the developerWorks article,
Create a Simple HTTP Web Services Gateway Service with WebSphere Application Server V6, to expose a simple Web service through the bus. You will not be able to progress any further until you have done this.
With our mediation coded and built we can now deploy it to WebSphere Application Server in preparation for associating it with a Web service. To do this:
- Install the DeployableMediation application
Install your recently exported DeployableMediation.ear file to WebSphere as you would any other Enterprise Application (Applications > Install New Application from the administration console).
- Create a mediation on the DeveloperWorksBus
From the WebSphere Admin Console:
- Click on Service integration > Buses > DeveloperWorksBus > Mediations > New
- Use the following values for your mediation. See Figure 4 below for an example of defining your mediation:
Mediation name: WebServicesDebugMediation
Handler list name: WebServicesDebugMediationHandler
Figure 4. Define a mediation
Associate mediations with Web services
With the mediation defined it is now available to be used by any Web services we have defined in our service integration bus. In this example we will associate it with the DeveloperWorksGatewayService
we created earlier. Figure 5 shows details of the steps we perform in this task.
From the WebSphere Admin Console click on Service integration > Buses > DeveloperWorksBus > Web service gateway instances > DeveloperWorksGateway > Gateway Services > DeveloperWorksGatewayService Click on the Request mediation dropdown list and select the WebServicesDebugMediation that you just defined. - Finally click on the Request mediation bus member dropdown list and select the server that you have defined your bus on.
Note 1: When associating a mediation with a Gateway service you can choose to associate a "Request mediation", a "Response mediation" or both - the difference between the two is that the former operates on Web
services messages flowing into the bus *before* they have been passed to the target Web service, whereas the latter operates on messages being returned to the client *after* they have passed through the target Web service. Deciding which to choose will depend
largely on the behaviour you want to apply to messages flowing through your setup.
Note 2: If you do not have a Gateway service available it is possible to mediate the two other types of Web service you may have defined on your bus - inbound and outbound services. To do this from your administration console simply
click on Service integration --> Buses --> YourBusName --> Destinations then select the checkbox next to the destination you wish to apply the mediation to, click the "mediate" button and follow the steps in the
mediation wizard.
Figure 5. Associate a mediation with a Web service
|
Test your mediation
With our mediation in place we can now test it by invoking our Gateway service - The simplest way to do this is to take advantage of the powerful Web Services Explorer tool provided by Rational Application Developer. This tool can be used to invoke
any Web service simply by providing it with the URL of the associated WSDL file, and is an invaluable way of quickly and easily sending test messages to your Web service. To test our mediation with it:
- Enable the Web Services Explorer
From within Rational Application Developer click on Window > Preferences > Workbench > Capabilities and ensure that the "Web Service Developer" box is ticked, as per Figure 6.
Figure 6. Enable the Web services explorer in Rational Application Developer
Launch the Web Services Explorer
Switch to the J2EE perspective and click on Run > Launch the Web Services Explorer
- Load the Gateway service WSDL
- In the Web Services Explorer window navigate to the WSDL page by clicking on the icon second from the right of the toolbar.
- In the WSDL URL field enter the path to your Gateway WSDL and click the "Go" button. Your WSDL should take the following format:
http://YourHostname:YourPort/wsgwsoaphttp1/soaphttpengine/DeveloperWorksBus/
DeveloperWorksGatewayService/YourNodeName_YourServerName_SOAPHTTPChannel1_InboundPort?wsdl
For example:
http://localhost:9081/wsgwsoaphttp1/soaphttpengine/DeveloperWorksBus/
DeveloperWorksGatewayService/L3LDP89Node02_server1_SOAPHTTPChannel1_InboundPort?wsdl
- Send a test message to your Gateway service
- From the main window in the Web Services Explorer click on the "setReturnString" operation from the newly loaded WSDL.
- Enter a test string to send to your Web service in the "string" box and click the "Go" button to invoke the service, as per Figure 7 below:
Figure 7. Invoke the Gateway service
- Verify that the mediation was executed successfully
With the successful invocation of your service you should see your string returned to the status window of the Web Services Explorer, indicating that the service was called and returned without error. Our main interest at this stage though is in the mediation
that we developed, so at this point you should check your WebSphere SystemOut logfile to verify that the mediation was executed successfully. You should see an entry in your logfile similar to that shown in Listing 4 below - if you do
congratulations ! You've just successfully written, deployed and invoked a mediation to inspect incoming Web services messages to the DeveloperWorksGatewayService.
Listing 4. Mediation output
****>> mediation.handlers.WebServicesDebugMediation: Mediation starting
****>> mediation.handlers.WebServicesDebugMediation: ------------------------------
****>> mediation.handlers.WebServicesDebugMediation: Incoming Web services message:
****>> mediation.handlers.WebServicesDebugMediation: ------------------------------
****>> mediation.handlers.WebServicesDebugMediation: OperationName = setReturnString
****>> mediation.handlers.WebServicesDebugMediation: MessageName = setReturnStringRequest
|--10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error: The previous line is longer than the max of 90 characters ---------|
****>> mediation.handlers.WebServicesDebugMediation: Parameter value = MyTestString
****>> mediation.handlers.WebServicesDebugMediation: ------------------------------
StringService Receives and Returns: MyTestString
|
From this output we can see that our mediation was called and successfully inspected the incoming message, pulling out the operation details and the string value that we passed in. All this happened before the target Web service was invoked, but had we
applied the mediation as a "Response mediation", this inspection would have had happened after the target Web service was called.
|
Modify your mediation for more verbose output
Whilst our first attempt at a Web services debug mediation gave us some useful output, it did have a number of limitations that we may want to address to make it more robust. Most notably:
- We aren't able to examine any information about the message header or attachments
- We have a hardcoded parameter name ("s") when we examine the payload of the incoming message
What we can do is modify our mediation to avoid these kind of pitfalls by using some of the powerful features of the SDO API to inspect the incoming message in a more dynamic fashion. Try replacing the
printNodeData() method in your mediation with that provided in Listing 5 below. This revised method takes an incoming SDO data object and inspects all of the fields and values in it,
without any of the drawbacks of having to hardcode parameter or object values.
Listing 5. Modify your mediation for more verbose output
private void printNodeData(DataObject dataObj, String indent) {
Iterator iter = dataObj.getType().getProperties().iterator();
while (iter.hasNext()) {
Property prop = (Property) iter.next();
// Get details from the SDO message
String elementName = prop.getName();
String elementType = prop.getType().getName();
boolean isContainer = prop.isContainment();
boolean isMany = prop.isMany();
// Print out the name of the property and the value (if it has one)
if(elementType.equalsIgnoreCase("String")) {
recordInLog(indent + elementName + " = " + dataObj.getString(elementName));
} else {
recordInLog(indent + elementName);
}
// If the dataObject has children deal with them here
if(isContainer) {
// If we have a list object, inspect it
if (isMany) {
List dataList = dataObj.getList(elementName);
if(dataList.isEmpty()) {
recordInLog(indent + " List is empty");
} else {
recordInLog(indent + " List contains " + dataList.size() + " entries");
}
} else {
// We have another data object so lets inspect it to find out what it contains
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error: The previous line is longer than the max of 90 characters ---------|
printNodeData(dataObj.getDataObject(elementName), " ");
}
}
}
}
|
If we re-deploy our updated mediation application to WebSphere and try invoking our Gateway service again, we can immediately see the benefits of more verbose output in the System logs (see Listing 6 below).
Listing 6. Modified mediation output
****>> mediation.handlers.WebServicesDebugMediation: Mediation starting
****>> mediation.handlers.WebServicesDebugMediation: ------------------------------
****>> mediation.handlers.WebServicesDebugMediation: Incoming Web services message:
****>> mediation.handlers.WebServicesDebugMediation: ------------------------------
****>> mediation.handlers.WebServicesDebugMediation: operationName = setReturnString
****>> mediation.handlers.WebServicesDebugMediation:
messageName = setReturnStringRequest
****>> mediation.handlers.WebServicesDebugMediation: messageType = input
****>> mediation.handlers.WebServicesDebugMediation: headers
****>> mediation.handlers.WebServicesDebugMediation: List is empty
****>> mediation.handlers.WebServicesDebugMediation: attachments
****>> mediation.handlers.WebServicesDebugMediation: List is empty
****>> mediation.handlers.WebServicesDebugMediation: body
****>> mediation.handlers.WebServicesDebugMediation: parameters
****>> mediation.handlers.WebServicesDebugMediation: s = MyTestString
****>> mediation.handlers.WebServicesDebugMediation: --------------------
StringService Receives and Returns: MyTestString
|
|
Modify your mediation to amend SOAP message content
So far our mediation has just been concerned with reading data from incoming messages - what if we wanted to modify that data instead ? Mediations are powerful enough to be able to do this through the use of the SDO API. Included below
in Listing 7 is a simple method to take an SDO DataObject and modify a user specified value. Try adding this method to your WebServicesDebugMediation class.
Listing 7. Add a new helper method to modify message data
private void modifyNodeData(DataObject dataObj,
String dataTypeName,
SIMessage msg,
DataGraph graph) throws
SIMessageDomainNotSupportedException,
SIDataGraphSchemaNotFoundException,
SIDataGraphFormatMismatchException,
SIMessageException {
// Debug information for the logs
recordInLog("Modifying incoming message...");
// Get the original payload value
String originalValue = dataObj.getString(dataTypeName);
recordInLog("Original value is: " + originalValue);
// Modify the payload
String modifiedValue = originalValue +
"_MODIFIED_BY_WebServicesDebugMediation";
dataObj.setString(dataTypeName, modifiedValue);
recordInLog("Modified value is: " + modifiedValue);
// Save the modified version to the SDO dataGraph
String format = msg.getFormat();
msg.setDataGraph(graph, format);
}
|
Now just update the handle() method of your mediation to include the code in Listing 8 below to ensure that we call the new modifyNodeData() method. In this calling code we
pass in the parameters DataObject and the name of the data type we want to change. We also pass in the SIMessage and the DataGraph, both of which are needed to save our amended string.
Listing 8. Update your handle() method
...
printNodeData(infoNode, "");
DataObject parameterNode = infoNode.getDataObject("body/parameters");
String dataTypeName = "s";
modifyNodeData(parameterNode, dataTypeName, msg, graph);
recordInLog("------------------------------");
...
|
To test our new mediation code simply re-deploy the updated mediation application to WebSphere and use the Web Services Explorer to call the Gateway service. After doing this examine the WebSphere
SystemOut logfile - you should see output similar to that listed in Listing 9 - note that the Web service is called with the newly modified string ! As a further check examine the
status window of the Web Services Explorer - you will notice that the returned string from the Web service is the version modified by our mediation.
Listing 9. Message modifier mediation output
****>> mediation.handlers.WebServicesDebugMediation: Mediation starting
****>> mediation.handlers.WebServicesDebugMediation: --------------------
****>> mediation.handlers.WebServicesDebugMediation:
Incoming Web services message:
****>> mediation.handlers.WebServicesDebugMediation: -------------------
****>> mediation.handlers.WebServicesDebugMediation: operationName = setReturnString
****>> mediation.handlers.WebServicesDebugMediation: messageName = setReturnStringRequest
****>> mediation.handlers.WebServicesDebugMediation: messageType = input
****>> mediation.handlers.WebServicesDebugMediation: headers
****>> mediation.handlers.WebServicesDebugMediation: List is empty
****>> mediation.handlers.WebServicesDebugMediation: attachments
****>> mediation.handlers.WebServicesDebugMediation: List is empty
****>> mediation.handlers.WebServicesDebugMediation: body
****>> mediation.handlers.WebServicesDebugMediation: parameters
****>> mediation.handlers.WebServicesDebugMediation: s = MyTestString
****>> mediation.handlers.WebServicesDebugMediation:
Modifying incoming message...
****>> mediation.handlers.WebServicesDebugMediation: Original value is: MyTestString
****>> mediation.handlers.WebServicesDebugMediation: Modified value is:
MyTestString_MODIFIED_BY_WebServicesDebugMediation
****>> mediation.handlers.WebServicesDebugMediation: ----------------------
StringService Receives and Returns:
MyTestString_MODIFIED_BY_WebServicesDebugMediation
|
|
Using mediations to route and clone SOAP messages
Dan Murphy's article, A practical introduction to message mediation -- Part 2 has step-by-step instructions for creating mediations to both route and clone messages flowing across the bus, including sample code and best practices. Although the article focuses on JMS messages, the high-level concepts and much of the code can be applied to SOAP messages as well. If you want to extend the power of the Web services debugger mediation we have created, why not use some of the code tips from Dan's article to route and clone your incoming Web service message to other bus destinations ?
Summary
This article has extended our understanding of the technologies we can use to manipulate Web services messages in the service integration bus within WebSphere. We have introduced the concept of using mediations to inspect messages, and have explored the reasons you may find them preferable to using JAX-RPC Handlers. As well as covering some of the theory of mediation programming we have written, built, deployed and tested a sample mediation to debug Web services messages flowing across a Gateway service in our bus. We also extended the mediation to provide more verbose debugging information and added more code to enable it to modify in-flight messages. Such a mediation could be extended further to route and clone messages using more advanced mediation programming techniques. For further mediations articles be sure to check out the excellent JMS series in the Resources section at the end of this article.
Downloads | Description | Name | Size | Download method |
|---|
| Sample code | ws-mmsib2code.zip | 1.8KB | HTTP |
|---|
| sample web service | Gateway_Sample.zip | 1581KB | HTTP |
|---|
Resources -
Part 1 of this series, "Manipulate Web services messages using the Service Integration Bus, Part 1: JAX-RPC handlers and the SIBus" (developerWorks, May 2005) explores the powerful Web services message manipulation features of the SIBus.
-
"Create a Simple HTTP Web Services Gateway Service with WebSphere Application Server V6" (developerWorks, updated July, 2005) shows you how to To create the sample Web service used in this article.
-
Check out "Configure a Service Integration Bus in a network deployment environment" (developerWorks, March, 2005) for details on configuring a service integration bus in a network deployment environment.
-
A practical introduction to message mediation, Part 1 provides a good general introduction to mediations.
-
A practical introduction to message mediation, Part 2 describes how to route messages to different destinations.
-
A practical introduction to message mediation, Part 3 shows how to modify JMS message content.
-
A practical introduction to message mediation, Part 4 shows how to use XSLT to modify JMS messages that contain XML.
-
A practical introduction to message mediation, Part 5 covers mediation of request/response style message interactions.
-
"Introduction to Service Data Objects" (developerWorks, September, 2004)
offers comprehensive overview of SDO.
-
The WebSphere Version 6 Web Services Handbook (IBM Redbooks, February 2005)
contains a useful chapter on the use of Web services with the service integration bus.
-
The WebSphere version 6.0 InfoCenter contains useful documentation on working with the service integration bus.
About the author | 
| | Chris Whyley is a technical leader in Web services testing at the IBM Hursley Software Laboratory in the UK, where he helps
to put Service Integration Bus technologies through their paces. Chris has worked with a wide range of Web services technologies across
several releases of WebSphere Application Server, and is co-author of the WebSphere Version 6 Web Services Handbook. You can contact Chris at whyleyc@uk.ibm.com. |
Rate this page
| |
