Introducing mediations

IBM® WebSphere® Application Server (WAS) version 6.0 implements the Enterprise Service Bus vision by introducing the Service Integration Bus (hereafter referred to as the bus) concept. A bus is a component -- made up of interconnected servers and clusters -- that enables integration between loosely-coupled applications and services. Applications connect to the bus and are supported using message-based and service-oriented architecture.

The mediation is a mechanism for customizing the basic messaging behavior of the bus, introducing intermediary logic to it. Mediations define a flexible and powerful mechanism for the processing of in-flight messages between applications (those producing messages and those consuming messages). A mediation acts like an intermediary between these applications, typically providing functions like:

• Message restructuring: between the format of the producers and the format expected by the consumers.
• Message routing: static or dynamic, based on message content.
• Message distribution: to more than one destination
• Message augmentation: the addition of information to a message from another data source

Together, these capabilities can make it simple to integrate previously disparate applications. New software can be integrated with little or no impact on existing software, which protects your investment in existing applications, thereby reducing overall costs. Mediations also allow communicating applications to be decoupled; applications need not know the location of -- nor the physical or even logical structure of messages required by -- their communication partner. A mediation can interact with other applications and resources, either by sending new messages or by invoking the application or resource manager directly.

A bus can have a number of destinations. A destination is a logical address to which applications attach as producers or consumers. A mediation is also attached to a bus destination. When a producing application sends a message to a destination -- and the message meets the mediation criteria -- the mediation is executed and the message is transformed before any consumer can receive it. Effectively, a mediation is executed between the producers and the consumers.

A mediation is deployed as a mediation handler. Handlers can be grouped in handler lists. Various qualities of service attributes can be specified on the handler, and when defining the mediation administratively. Mediation handlers can be configured and parameterized.

Mediations run under a common bus identity, with access to destinations controlled by permissions belonging to the identity associated with the application's connection to the service integration bus. Mediations run under supported transactional attributes.

A mediation handler is implemented as a stateless session Enterprise JavaBeans" (EJB") component. It wrappers a mediation handler class that implements the com.ibm.websphere.sib.mediation.handler.MediationHandler interface, which has one method: public boolean handle(javax.xml.rpc.handler.MessageContext msgCtx) throws MessageContextException

This method is invoked by the mediation framework when the message arrives at the destination. The message context parameter that is passed in gives access to the message and its properties. This provides a way to query the various bus attributes and perform messaging operations.

The mediation must return true for the message to continue its journey through the bus, otherwise the message is discarded. If the mediation returns MessageContextException or a runtime exception, the message is sent to the exception destination.

IBM® Rational® Application Developer (hereafter referred to as IRAD) version 6.0 provides support for deploying and testing mediations. In addition, you can deploy mediations using the IBM® WebSphere® Application Server Toolkit, part of WAS 6.0.

Back to top

Describing the mediation sample

In the following section, we will show you how you can write and test a mediation. We will build a sample to show the use of the mediation.

A producer sends a message to a destination. A consumer receives the message. This is the typical way that two applications communicate asynchronously, as shown in Figure 1.

We will write a mediation that reroutes this message to a different destination, illustrated in Figure 2.

When the mediation is attached to the first destination, the message is rerouted to the new destination. Only consumers attached to the second destination would be able to receive the message.

A message has a forward routing path, which is a set of destinations to which a message is routed. It is defined when the message is created. With the mediation in place, when the message reaches the original destination, that destination is removed from the forward routing path. When the path is empty the message is available for consumers.

In this sample, we will overwrite the forward routing path of the mediated message in order to direct it to the new destination. In addition, we will modify the message body of the text message being sent to the destination, adding the prefix mediated:. This illustrates how mediation handlers can modify message context using SDO (Service Data Object) APIs.

Back to top

Step-by-step guide to mediations

The steps you need to complete to create your first mediation application are:

1. Build the application
2. Configure the bus and resources
3. Run and test the application

Back to top

Build the application

Start IRAD and open the Java" 2 Platform, Enterprise Edition (J2EE") perspective if it's not already open.

Create Java project

1. Click File > New > Java > Java Project.
2. Specify RoutingMediations as the project name and, in the Project Layout category, select Create Separate source and output folders.
3. Click Finish (Answer No if asked to switch perspectives).

This creates the Java Project that will contain the mediation handler class.

Set WAS version 6.0 as target server for the Java Project

1. Right-click RoutingMediations in the Project Explorer (under Other Projects) and click Properties on its context menu.
2. For Target runtime, select WebSphere Application Server v6.0 from the list (as shown in Figure 3).

This will add all the necessary runtime archives to the classpath of the RoutingMediations project.

Create Mediation Java Class

1. Click File > New > Java > Class.
2. Select RoutingMediations/src as the source folder, then enter myPackage as the package name and RoutingMediation as the class name.
3. Click Add next to Interfaces and select MediationHandler .
4. Click Finish.

This will create the skeleton of your mediation handler class.

Next, edit the handle method of the newly generated class to contain the following code:

1 public boolean handle(MessageContext context) ...{
	   
2      SIMessageContext ctx =(SIMessageContext)context;
3    String busName = ctx.getSession().getBusName();					
4      SIMessage message = ctx.getSIMessage();			
5      List frp = message.getForwardRoutingPath();
		
6      String newDestination = "secondDestination";
7      SIDestinationAddressFactory factory =        
         SIDestinationAddressFactory.getInstance();
8      SIDestinationAddress newAddress = factory.
         createSIDestinationAddress(newDestination,busName);
	
9      frp.clear();
10     frp.add(newAddress);
11     message.setForwardRoutingPath(frp);

try {
12     String jmsText = SIApiConstants.JMS_FORMAT_TEXT;
13     DataGraph graph = message.getNewDataGraph(jmsText);
14     DataObject body = graph.getRootObject();

15     if (body.isSet("data")) {
16          String oldPayload = body.getString("data/value");
17          String payload= "Mediated message: "+ oldPayload;
18          DataGraph newGraph = message.getNewDataGraph(jmsText);
19          newGraph.getRootObject().set("data/value", payload);
20          message.setDataGraph(newGraph, jmsText);
     }
}
catch (Exception e) {
21     e.printStackTrace();
22     throw new MessageContextException();
}
23     return true;
}	

Code explanation:

Line 1: The method implemented by the mediation handler class takes as an argument a javax.rpc.MessageContext. This argument is passed by the runtime mediation framework, and can be queried for properties and values.

Line 2: We need to pass the argument to a SIMessageContext object. This way, we'll have access to more methods and information in order to implement our mediation.

Note: Lines 2-11 modify the forward routing path of the message.

Line 3: Query the message context for the bus name on which the mediation runs.

Line 4-5: Extract the SIMessage object from the message context and its forward routing path (that is, where the message would go next) in the form of a list of SIDestinationAddress objects.

Line 6: The name of the new destination is hard coded in the mediation.

Line 7-8: Acquire an instance of the singleton class SIDestinationAddressFactory and then use it to create a new destination object, passing as strings its name and the bus name on which the destination is created.

Line 9-11: Clear he forward routing path of the message of the previous values, add the new destination to the path, and set this new destination on the message.

Note: Lines 12-23 modify the message content using SDO APIs. For more information on SDO, see the Resources section later in this article.

Line 12: We make the assumption that the mediated message is a Java" Message service (JMS) text message.

Lines 13-14: Extract the data graph representation of the method and then the message body.

Line 15: Check whether the message has a body.

Lines 16-17: Extract the message payload and add a new prefix to it.

Lines 18-20: Create a new data graph from the message, assign the new message payload to it, and then re-assign the data graph to the message.

Lines 21-22: Exception processing. We can use any logging mechanism and wrap the exception thrown into a MessageContextException. The message is put to the exception destination.

Line23: Mediation handler class must return true for the message to continue its path through the bus.

Note: in our example we have added a few System.out statements so that the various variables can see their values.

Create EJB Project to hold the mediation handler

1. Click File > New > EJB > EJB Project
2. Enter the name RoutingMediationsEJB.
3. Accept all defaults and click Finish.
4. Add the Java Project to the classpath of the EJB project by right-clicking the RoutingMediationsEJB project, and on its Properties->Java Build pane, select Projects and click RoutingMediations.

This will add the project to the EJB project classpath and make the handler class visible.

Create Mediation Handler

1. Open the deployment descriptor editor by expanding the EJB Projects folder in the Project Explorer.
2. Then select RoutingMediationsEJB and double-click on the Deployment Descriptor.
3. Switch to Mediation Handlers tab and Click Add.
4. As shown in Figure 4, enter RoutingHandler for Name and enter (or select by clicking Browse) myPackage.RoutingMediationHandler for Handler class.

1. When you enter a name, the wizard instantiates the class in the right context (hence, there is a small delay the first time you do this) and returns the handler class properties. In this example, there are none.
2. Click Finish.

The wizard creates a mediation handler for you. You can examine the artifacts that have been created (shown in Figure 5): a stateless session EJB component with specific deployment attributes.

The mediation handler is part of a handler list with the same name. You will use the handler's (and handler list's) name, RoutingHandler, when configuring a mediation.

These options are available in the Advanced section, and will be examined in Part 2 of this paper.

Back to top

Configure the bus and define resources

Start Server Admin Console

1. From the Servers view, right-click WAS 6.0 and from the context menu click Debug.
2. When the server starts, from the same menu, select Run Administrative Console.

Note: This menu item is available only when the server has started.

The next configuration steps are done in the admin console in an interactive manner. Alternatively, you can write a Java" Application Control Language (JACL) script for all admin operations and run it using the Run external admin script option from the menu. For more information on wsadmin commands check the Resources section in this document.

After each admin step you will need to follow the Save links to save the changes you make to the configuration.

Create Bus and Add server to the bus

1. In the Server Integration > Buses folder of the Admin console, click New to create a bus called MediationTestBus.
2. Keep all the defaults and click OK to save the configuration. This creates a bus, as shown in Figure 6.

1. Select the newly created bus (Figure 6). Under the Additional Properties heading, we will use the following links:

• Bus members to add the local server to the test bus
• Mediations to define a Mediation object
• Destinations to define our two destinations, attach the mediation to the first destination, and then to see the mediated message on the second destination

Add a server to the bus

1. Follow the Bus Members link and click Add.
2. Select the Server option
3. Select the local host from the drop-down list.
4. Confirm the addition and save the configuration.

Create a mediation object

1. Follow the Mediations link and click New.
2. Give the mediation the name MyFirstMediation
3. For the handler list name, use RoutingHandler, the name specified in the Mediation Handler wizard.
4. Click OK to save the configuration.

Create two destinations

1. Follow the Destinations link and click New.
2. Select Queue on the first page and click Next.
3. Enter firstDestination as Identifier and click Next.
4. Now add the destination to the mediationTestBus and select Finish.

This creates a destination (or queue), as shown in Figure 9 following.

Repeat the above steps and create a destination called secondDestination.

Attach mediation to destination

1. Follow the Destinations link and select the firstDestination destination check box
2. Next, click the Mediate button.
3. On Step 1: Select a mediation, select MyMediation from the list (Figure 10)
4. For Step 2: Assign the mediation to a bus member, select mediationTestBus
5. For Step 3: Confirm mediation of destination, confirm and save the configuration.

Creating JMS Resources

At this point, you will need to create the JMS resources for this sample.To do this, click Resources > JMS Providers > Default Messaging. You will use the Queues and Queue connection factories links.

Create JMS Queues

1. Follow the Queues link and click the New button.
2. Specify the following values, as shown in Figure 11:

• Name : Queue1
• JNDI name : Q1
• Bus name : select mediationTestBus
• Queue Name : firstDestination

1. Repeat the above steps for the following values:

• Name : Queue2
• JNDI name : Q2
• Bus name : select mediationTestBus
• Queue Name : secondDestination

The configuration steps are nearly completed. The last thing that is needed is a queue connection factory -- a resource that is only needed by the messaging client to send messages to destination.

Create Queue Connection Factory

1. Follow the JMS Queue Connection Factory link and click New.
2. Specify the following values:

• Name : QueueConnectionFactory
• JNDI name : QCF1
• Bus name : select mediationTestBus

Install and test the mediation

1. Switch back to the IRAD toolkit and select the Servers view in the J2EE perspective (shown earlier in Figure 5).
2. Right-click the server and from the context menu select Add and remove projects, select RoutingMediationsEJBEAR, and click Finish.

Some server configurations require the server to be restarted. Creating new bus members requires a server restart. Right-click the server in the Servers view and from the context menu select Restart > Debug.

Optionally, you can set breakpoints in the mediation handler class to see when the mediation is invoked and to look at the available information.

Back to top

Sending a test message on the JMS queue

1. From the server's context menu, select Run universal test client. A web browser will launch with the Universal test client running.
2. Expand Utilities and select Send JMS Message.
3. Specify the following values:

• Queue JNDI Name: Q1
• Queue CF JNDI Name : QCF1
• Message : Hello

1. Click Send.

Note: The java debugger should stop if you have breakpoints set in your handle method of the RoutingMediation mediation handler class.

1. You can see results of the mediation running -- namely, the rerouted message -- using the WAS 6.0 Admin Console, as shown in Figure 12.

1. From the Buses > mediationTestbus > Destinations folder (shown in the J2EE admin console in Figure 7), select the secondDestination link, which should yield the results shown in Figure 13.

1. Under Queue Points, select Queue2
2. Click the Runtime tab and then the Messages link. There should be one message on the secondDestination
3. If you follow the Message Body link you will see Mediated message: followed by the text you have entered in the client.

At this point, you can unmediate the firstDestination, send a new message with the client and see the message arriving on Queue1.

Back to top

Summary

Mediations are a powerful mechanism for plugin to the system bus. This article has introduced the basic concepts and has shown how to build the first mediation. In the second part, we will explore more concepts related to the mediation.

Resources

Learn

• Introduction to Service Data Objects (developerWorks, January 2005) introduces you to next-generation data programming with Service Data Objects (SDO).
  
  
• Getting started with the Eclipse Platform provides a history and overview of Eclipse, including details on how to install Eclipse and plug-ins.
  
  

Get products and technologies

• Get the evaluation version of Rational Application Developer from the Trials and betas page
  
  
• For technical resources about Rational's products, visit the developerWorks Rational content area. You'll find technical documentation, how-to articles,education, downloads, product information, and more. For specific information about Rational Application Developer, visit the RAD technical resources page.
  
  
• Find more product related information by visiting the Rational Application Developer product page.
  
  
• For details and more information about WebSphere Application Server, visit the WebSphere Application Server Information Center.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Ask questions about Rational Application Developer in the Rational Software Architect, Software Modeler, Application Developer and Web Developer forum. Be sure to peruse the Help pages within Rational Application Developer. These pages provide a wealth of information, including multimedia tutorials and walkthroughs.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introducing mediations
• Describing the mediation sample
• Step-by-step guide to mediations
• Build the application
• Configure the bus and define resources
• Sending a test message on the JMS queue
• Summary
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers