Introduction to the Service Integration Bus

The Service Integration Bus (SIBus) is a key part of IBM® WebSphere® Application Server V6.0 (Application Server), allowing users to take advantage of a host of messaging and Web services options. Incorporating the functionality of the Web Services Gateway, the SIBus builds upon the asynchronous messaging features of WebSphere and allows users to manage Web services through administrative panels and commands. Existing Web services can be exposed through the SIBus, which you can set up to act as a proxy, allowing users to expose Web services at new destinations on the SIBus, and manipulate incoming and outgoing message content (see Figure 1 below). By decoupling the link between service requestors and providers, the SIBus gives users tighter control over the services they manage, allowing:

• Secure exposure of Web services hidden behind a company firewall
• Protocol transformation of incoming messages before they are passed to target services (for example, from SOAP/HTTP to SOAP/JMS)
• The ability to inspect and then route incoming messages to different services
• Straightforward management of message handlers
• Advanced message options for asynchronous communication (such as prioritized message delivery and message persistence)

Back to top

Why access a message?

Users might want to access a Web services message passing through the SIBus for many reasons. At the most basic level, message inspection is useful for logging purposes, as system administrators might want to keep a record of a particular transaction passing through an application server -- for auditability or simply for building up a record of the most regularly used Web services. In more advanced configurations, users might want to access messages in order to inspect authentication information (when using WS-Security), or to deal with transactions (when WS-Transaction is involved).

Message inspection is only one aspect of this processing though. One of the most powerful features of message handlers is their ability to manipulate and augment message content and message header information. Using the options available in the SIBus, you can route messages to different targets, change parts and operation names, and transform whole messages from one format to another. On top of this, you can also construct handler chains to further increase control over message flow and content.

Back to top

Manipulating messages: Handlers or mediations?

Users have two options when using the SIBus to manipulate Web services messages: JAX-RPC handlers and mediations. Each has a unique set of advantages and disadvantages. This section examines the two approaches before attempting to unravel when and why you might want to use each of them (for a summary, see Table 1 below).

JAX-RPC handlers

JAX-RPC handlers have become increasingly popular within the J2EE community as the de-facto way of manipulating in-transit Web services message content. They are well defined, straightforward to deploy, use easily recognizable deployment descriptors, and allow users fine-grained control over most aspects of SOAP messages, whether over JMS or HTTP. You can find the latest formal specification for JAX-RPC handlers in JSR 921 (see Resources). This specification describes how you can implement handlers in either the client or server environment. Regardless of where you place them though, the characteristics of JAX-RPC handlers are the same -- They are independent of particular transports, capable of modifying certain types of SOAP body and header message content, and can process both inbound or outbound requests, giving users the ability to examine or modify a SOAP message before it is passed to the ultimate receiver. Multiple handlers can be chained together in JAX-RPC handler lists, which allow fine-grained control over the order in which they are executed. While handlers are often easy to use and can be dynamically deployed into the SIBus, they are not able to modify every aspect of the SOAP message -- operation information, part names, and sequences, for instance, are all off limits.

Mediations

Mediations are a new concept in WebSphere V6.0, and are designed to perform a similar function to JAX-RPC handlers. They can access and modify in-flight messages within Application Server. Unlike JAX-RPC handlers, however, they also have the ability to examine non-SOAP content, such as SDO or JMS messages, giving users greater freedom over the types of message they can access. Mediations can also take control over message delivery and provide powerful options for re-routing messages to alternative destinations, or clone messages and spray them out to multiple destinations for further processing. You can also use mediations to perform complex transformations on messages to change them from one format to another. In short, although mediations are limited to running within the server container, they provide a host of options for managing messages, and should be considered as a serious alternative to JAX-RPC handlers when you need more powerful manipulation, or when you are operating in an environment with mixed styles of messages. Part 2 of this article discusses mediations in detail.

Table 1. Comparing capabilities of SIBus message handlers

Back to top

Writing JAX-RPC handlers

You can find abundant literature on writing useful JAX-RPC handlers, and many good code examples are available for reuse from within the Java™ community. Some of the best practices for coding handlers include:

• Try to write discreet function in handlers. (This enables them to be more easily combined together using handler lists.)
• Write function that might be useful to both your client and server processes.
• Follow the specifications to avoid compatibility problems.

The example below shows how to write a simple handler to log details of the incoming SOAP message to standard output. Such a handler can be extremely useful for helping to debug problems within a Web services application. Poorly formed SOAP messages can sometimes be difficult to spot, can be caused by a number of factors, and can hamper application development and performance. You can copy code for this handler from Listing 1 below, or download it from the Resources section at the end of this article.
Note: As a prerequisite for using this handler with a Web service in the SIBus, ensure that you have completed the steps in the developerWorks article, Create a simple HTTP Web services gateway service with WebSphere Application Server V6 , to create a simple service. Download the associated code from the article, or from the "More downloads" section below.

// Compile with j2ee.jar and xml.jar
package com.ibm.developerworks;

import java.util.Iterator;
import javax.xml.rpc.handler.*;
import javax.xml.rpc.handler.soap.*;
import javax.xml.soap.*;

public class DevWorksHandler1 implements javax.xml.rpc.handler.Handler {	
	
	public void init(HandlerInfo config) {
		System.out.println("****>> DevWorksHandler1: init()");
	}
	
	public boolean handleRequest(MessageContext context) {
		System.out.println("****>> DevWorksHandler1: handleRequest()");
		
		try {			
			// Get existing MessageContext and from it the SOAP Envelope	
			SOAPMessageContext smc = (SOAPMessageContext)context;
			SOAPMessage msg = smc.getMessage();
			SOAPPart sp = msg.getSOAPPart();			
			SOAPEnvelope se = sp.getEnvelope();
			
			// Get child elements of the SOAP Body
			Iterator iter = se.getChildElements();
			
			// Print out all the elements
			while (iter.hasNext()) {
				  SOAPElement sel = (SOAPElement) iter.next();
				  System.out.println(sel);			  
			}

		}
		catch (Exception e) {
			System.out.println("****>> DevWorksHandler1: Exception raised");
		 	e.printStackTrace();
		}
      		
		return true;
	}
	
	public void destroy() {
		System.out.println("****>> DevWorksHandler1: destroy()");
	}
	
	public javax.xml.namespace.QName[] getHeaders() {
		System.out.println("****>> DevWorksHandler1: getHeaders()");
		return null;
	}
	
	public boolean handleResponse(MessageContext context) {
		System.out.println("****>> DevWorksHandler1: handleResponse()");
		return true;
	}
	
	public boolean handleFault(MessageContext context) {
		System.out.println("****>> DevWorksHandler1: handleFault()");
		return true;
	}

}

Back to top

Deploying JAX-RPC handlers to the SIBus

To make any JAX-RPC handler available for use in the SIBus, you must first ensure that the class is available and loaded into your application server. The simplest way to do this is to deploy a .jar file containing the handler(s) you wish to use into the WebSphere "classes" directory. By restarting the application server process, any handlers you have included in this directory will be picked up by the server and ready to use.

After doing this, you are then in a position to define the handler in the SIBus. You can do this from the Application Server administrative console (see Figure 2 below):

1. In the navigation pane select Service integration --> Web services --> JAX-RPC Handlers.
2. From the main window, click New.
3. Fill in the details for your handler. The name and description are user-defined, but the class name must match the full class name (with packages) of the handler you wish to deploy. In this case use:
   Name : DevWorksHandler1
   Class Name : com.ibm.developerworks.DevWorksHandler1
4. Click OK to save your new configuration.

Back to top

Using JAX-RPC handler lists

After you deploy your handler into the SIBus, you then need to add it to a JAX-RPC handler list -- the order in which handlers appear in these lists determines the order in which they are executed. This feature allows users to dynamically compose functions in the SIBus and ensure they have full control over the message path through their JAX-RPC handlers. In this example, even with only one handler, you will still add it to a list so that you can later associate this list with a service and allow the option of adding more handlers to the list in the future.

To add your handler to a list using the administrative console (see Figure 3 below):

1. In the navigation pane select Service integration --> Web services --> JAX-RPC Handler Lists.
2. From the main window, click New.
3. Fill in the details for your handler. The name and description are user-defined. In this case use:
   Name : DevWorksHandlerList
   
4. Click on DevWorksHandler1 followed by the Add button to place it into the list.
5. If you were working with more than one handler, you could use the Up and Down buttons to determine the order in which they are executed.
6. Click OK to save your new configuration.

Back to top

Associating JAX-RPC handler lists with services

Now that you have defined your JAX-RPC handler list, any service defined in the SIBus can use it. Typically, you would want to associate the list with an inbound or outbound service, two of the main administrative building blocks for exposing Web services in the SIBus. Binding the handler list to your bus service gives you the power to examine and manipulate in-flight SOAP messages before they reach their final destination (for more detail on setting up and using the SIBus please see the various articles and books in Resources). The example below assumes that you have followed the instructions in the recent developerWorks article, "Create a Simple HTTP Web Services Gateway Service with WebSphere Application Server V6" (see Resources).

To add your new handler list to a service using the administrative console (see Figure 4 below):

1. In the navigation pane select Service integration --> Buses --> DeveloperWorksBus --> Inbound Services --> DeveloperWorksGatewayService --> Inbound Ports --> SOAPHTTPChannel1InboundPort.
2. From the main window, select the DevWorksHandlerList from the JAX-RPC handler drop-down list.
3. Click OK to save your new configuration.

Back to top

Testing your JAX-RPC Handler

Assuming you have followed the steps so far, you should now be able to test your newly configured JAX-RPC handler list by invoking the associated gateway service, using the sample client provided in the related developerWorks article. On sending a string to the gateway service, the JAX-RPC handler will be invoked and produce the following message in the server SystemOut.log file:

Listing 2. JAX-RPC handler output

****>> DevWorksHandler1: init()
****>> DevWorksHandler1: handleRequest()
<soapenv:Header
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<soapenv:Body
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <p124:setReturnString xmlns:p124="http://service.string">
       <arg_0_1>CJW-TestString</arg_0_1>
     </p124:setReturnString>
</soapenv:Body>
StringService Receives and Returns: CJW-TestString
****>> DevWorksHandler1: handleResponse()

Back to top

Summary

This article introduced the two main approaches to manipulating in-flight Web services messages in the SIBus within WebSphere -- JAX-RPC handlers and mediations -- and the advantages and disadvantages of both approaches. The example showed how to code and deploy a JAX-RPC handler into the SIBus to inspect and output the contents of an incoming SOAP message. Such a handler helps debug problems with Web services applications, or simply acts as a 'heartbeat' to verify that requests are being received. Part 2 of this article will cover in detail the use of mediations to manipulate Web services messages in the SIBus.

Back to top

Downloads

Information about download methods

Resources

• Get an introduction to working with the Web Services Gateway in the SIBus with the developerWorks article, Create a Simple HTTP Web Services Gateway Service with WebSphere Application Server V6 (developerWorks, February 2005).
  
  
• Learn how to implement handlers in either the client or server environment with JSR 921, the latest formal specification for JAX-RPC handlers.
  
  
• Check out this Web service programming tip on How to create a simple JAX-RPC handler for more detail on programming handlers (developerWorks, November 2003).
  
  
• Read Configure a Service Integration Bus in a network deployment environment to learn how to install and configure SIBus scenarios across an IBM WebSphere Application Server V6.0.x cluster (developerWorks, March 2005).
  
  
• See A practical introduction to message mediation for a good general introduction to mediations (developerWorks, March 2005).
  
  
• Check out the WebSphere Version 6.0 InfoCenter for useful documentation on working with the SIBus.
  
  
• Read the WebSphere Version 6 Web Services Handbook, especially the chapter on the use of Web services with the SIBus (IBM Redbooks, February 2005).
  
  
• Find the Java RPC programming specification on the JCP site under the title, "Java APIs for XML based RPC (JAX-RPC) [JSR-101]."
  
  
• Find the updated specification for JSR 109 (J2EE Web services) under the title, "Implementing Enterprise Web Services 1.1 [JSR 921]."
  
  
• 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 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.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction to the Service Integration Bus
• Why access a message?
• Manipulating messages: Handlers or mediations?
• Writing JAX-RPC handlers
• Deploying JAX-RPC handlers to the SIBus
• Using JAX-RPC handler lists
• Associating JAX-RPC handler lists with services
• Testing your JAX-RPC Handler
• Summary
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

WebSphere Application Server can leverage its built in Web Services support to expose services to remote consumers in an industry-standard way.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and includes built in Web Services support.
• Article: Learn how to use of the JAX-WS programming model to create dispatch and dynamic proxy clients and how to create an asynchronous Web service client.
• Tutorial: This tutorial takes you through the steps to deploy Data Web Services to the WebSphere Application Server Community Edition.
• Demo: This demo shows how to extract and install the IBM Java Platform, Java EE 5 SDK with WebSphere Application Server.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers