Introduction

IBM® WebSphere® ESB V6.0.2 introduced WebSphere MQ bindings, which let you send and receive messages via WebSphere MQ. The MQ binding provides out-of-the box header data bindings to transform native MQ headers to DataObjects that can be used within a module. The supported headers are:

• MQMD
• MQRFH
• MQRFH2
• MQOpaqueHeader

The MQOpaqueHeader data binding deals with unrecognised MQ headers in a standard MQ format. It creates a DataObject with a structure id, version, structure length, encoding, ccsid, format, and flags. The rest of the data is set into a byte[].

Although MQ headers are dealt with by the MQOpaqueHeader data binding, the full structure of the header is not available to the application. It requires a custom header data binding that understands the full structure of the header and can create the required DataObject.

Products used in this article:

• WebSphere Integration Developer V6.1
• WebSphere ESB V6.1 Integrated Test Environment (included with WebSphere Integration Developer)
• WebSphere MQ V6.0.2.2

Modeling the header

This article uses the MQ Dead Letter Header (MQDLH) as the native MQ header. To represent the MQDLH in the module as a DataObject, you need to model the header as a Business Object. Here is the structure of the MQDLH :

1. Create a new library named MQCustomHeaderLibrary
2. Open the dependencies on the library, and under Predefined Resources, tick Schema for simple JMS Data Bindings, then click Save.
3. In the Library, create a new interface called MQBytesInterface.
4. Create a one-way operation, leaving the operation name as the default.
5. Change the type of input1 to JMSBytesBody and click Save to save the interface.
6. In the library, create a new business object called MQDLH.
7. Add the required fields:

The Encoding, CodedCharSetId, and Format fields are not modeled here, as they are mapped to the supplied MQControl Business Object. For more information on the MQControl, see Part 1 of this series. You will see below how to map these fields in the data binding.

Writing the Custom Header data binding

8. In the MQCustomHeaderLibrary, create a new Java class named MQDLHDataBindingImpl in package com.ibm.custom.data.binding that implements MQHeaderDataBinding.
9. Replace the contents with the code below:

package com.ibm.custom.data.binding;

import java.io.IOException;
import com.ibm.mq.data.MQDataInputStream;
import com.ibm.mq.data.MQDataOutputStream;
import com.ibm.websphere.bo.BOFactory;
import com.ibm.websphere.sca.ServiceManager;
import com.ibm.websphere.sca.mq.data.MQHeaderDataBinding;
import commonj.sdo.DataObject;

public class MQDLHDataBindingImpl implements MQHeaderDataBinding {

	private DataObject dObj;
	private String nextFormat;
	private int nextCCSID;
	private int nextEncoding;
	    
	//MQDLHDataBinding only understands "MQDEAD" format
	public boolean isSupportedFormat(String format)
	{
		return format.trim().equals("MQDEAD");
	}
	  
	public DataObject getDataObject()
	{
		return dObj;
	}

	public void setDataObject(DataObject dObj)
	{
		this.dObj=dObj;
	}
	  
	public void read(String format, MQDataInputStream input) throws IOException
	{
		//Check the Structure Id is the expected DLH
		String strucId=input.readMQCHAR4();
		if (!strucId.equals("DLH ")) throw new IOException
			("Malformed dead-letter header");
		//Check this is a version 1 header
		int version=input.readMQLONG();
		if (version!=1) throw new IOException("Unsupported DLH version");

		//Create the output DataObject
		BOFactory bof=(BOFactory)ServiceManager.INSTANCE.
			locateService("com/ibm/websphere/bo/BOFactory");
		DataObject dObj=bof.create("http://MQCustomHeaderLibrary", "MQDLH");
		dObj.setString("StrucId", strucId);
		dObj.setInt("Version", version);
		dObj.setInt("Reason", input.readMQLONG());
		dObj.setString("DestQName", input.readMQCHAR48());
		dObj.setString("DestQMgrName", input.readMQCHAR48());
		nextEncoding=input.readMQLONG();
		nextCCSID=input.readMQLONG();
		nextFormat=input.readMQCHAR8();
		dObj.setInt("PutApplType", input.readMQLONG());
		dObj.setString("PutApplName", input.readMQCHAR28());
		dObj.setString("PutDate", input.readMQCHAR8());
		dObj.setString("PutTime", input.readMQCHAR8());

		this.dObj=dObj;
	}

	public void write(String format, MQDataOutputStream output) throws IOException
	{
		output.writeMQCHAR4("DLH ");     // StrucId
		output.writeMQLONG(1);           // Version
		output.writeMQLONG(dObj.getInt("Reason"));
		output.writeMQCHAR48(dObj.getString("DestQName"));
		output.writeMQCHAR48(dObj.getString("DestQMgrName"));
		output.writeMQLONG(nextEncoding);
		output.writeMQLONG(nextCCSID);
		output.writeMQCHAR8(nextFormat);
		output.writeMQLONG(dObj.getInt("PutApplType"));
		output.writeMQCHAR28(dObj.getString("PutApplName"));
		output.writeMQCHAR8(dObj.getString("PutDate"));
		output.writeMQCHAR8(dObj.getString("PutTime"));
	}
	  
	public void setNextFormat(String format)   {nextFormat=format;}
	public String getNextFormat()              {return nextFormat;}
	public void setNextCCSID(int ccsid)        {nextCCSID=ccsid;}
	public int getNextCCSID()                  {return nextCCSID;}
	public void setNextEncoding(int encoding)  {nextEncoding=encoding;}
	public int getNextEncoding()               {return nextEncoding;}
}	

Description of the data binding

When implementing MQHeaderDataBinding, you need to implement several methods:

• isSupportedFormat receives a format and checks whether this data binding supports it. In this case it returns true only if the format matches the MQDLH format MQDEAD.
• getDataObject returns the DataObject created by the read method of this data binding.
• setDataObject sets the DataObject in this data binding.
• read reads the message header of incoming messages and create the required DataObject. In this case, the MQDLH Business Object is created and populated.
• write creates the message header for outgoing messages.
• setNextFormat sets the formatting of either the next header, or if this is the last header in the chain, the body of the message.
• getNextFormat gets the formatting of either the next header, or if this is the last header in the chain, the body of the message. The format field in this header is normally used to describe the format of the next part of the message, hence it returns the value retrieved by the read method.
• setNextCCSID sets the Coded Character Set Id of either the next header, or if this is the last header in the chain, the body of the message.
• getNextCCSID gets the Coded Character Set Id of either the next header, or if this is the last header in the chain, the body of the message. The ccsid field in this header is normally used to describe the ccsid of the next part of the message, hence it returns the value retrieved by the read method.
• setNextEncoding sets the encoding of either the next header, or if this is the last header in the chain, the body of the message.
• getNextEncoding gets the encoding of either the next header, or if this is the last header in the chain, the body of the message. The encoding field in this header is normally used to describe the encoding of the next part of the message, hence it returns the value retrieved by the read method.

The MQDataInputStream and MQDataOutputStream provide methods for reading and writing native MQ headers. For more information, see WebSphere ESB information center.

Using the Custom Header data binding in a mediation module

10. Create a new mediation module called MQCustomHeaderModule. Ensure that Create mediation component is ticked and then click Next.
11. Tick MQCustomHeaderLibrary and click Finish.
12. Add an import to the assembly diagram.
13. Wire the mediation component to the import. When asked to add a reference, select MQBytesInterface.
14. Right-click on Import1 and select Generate Binding => Messaging Binding => MQ Binding.
15. Specify your queue manager name, send destination, host name, server channel, and port of your WebSphere MQ installation.
16. Under Data Configuration, click Browse.
17. Select the Show predefined data bindings radio button.
18. Select MQ unstructured binary message, click OK, and then click OK again.
19. Right-click on the mediation component, select Add => Interface, select the MQBytesInterface, and then click OK.
20. In the Properties view of the Import on the Bindings tab, under User supplied MQ Header Data Binding Configuration, click Add.
21. Select the Show data binding classes radio button.
22. From the list of data bindings, select MQDLHDataBindingImpl and then click OK.

Your module should now look like this:

23. Double-click on the mediation component MQCustomHeaderModule to generate an implementation.
24. In the Mediation Flow Editor, wire operation1 to operation1 to create a flow.
25. In the Palette, select Transformation => Custom Mediation.
26. Add the custom mediation to the canvas.
27. Wire the input node to the input terminal of the custom mediation.
28. Wire the output terminal of the custom mediation to the callout node.
29. On the properties panel of the custom mediation, select the Details tab.
30. Click the Java radio button.
31. Replace the content with the code below and click Save.

//Retrieve the MQ header
MQHeaderType mqHeader = smo.getHeaders().getMQHeader();
//If there is no MQHeader 
if (mqHeader == null) {
	//Create the SMO MQHeaderType.  This contains all the MQ headers
	mqHeader = ServiceMessageObjectFactory.eINSTANCE.createMQHeaderType();
	//Set the MQHeader in the SMO
	smo.getHeaders().setMQHeader(mqHeader);
}

//Use BOFactory to create an instance of MQDLH
ServiceManager serviceManager = ServiceManager.INSTANCE;
BOFactory bofactory = (BOFactory) serviceManager.
	locateService("com/ibm/websphere/bo/BOFactory");
DataObject mqdlh = bofactory.create("http://MQCustomHeaderLibrary", "MQDLH");
//Populate the header
mqdlh.setString("StrucId", "DLH ");
mqdlh.setInt("Version", 1);
mqdlh.setInt("Reason", MQC.MQFB_APPL_TYPE_ERROR);
mqdlh.setString("DestQName", "SD");
mqdlh.setString("DestQMgrName", "QM");
mqdlh.setInt("PutApplType", MQC.MQAT_JAVA);
mqdlh.setString("PutApplName", "WebSphere ESB");
mqdlh.setString("PutDate", "20080319");
mqdlh.setString("PutTime", "0900");

//Get the current list of MQ Headers
List mqHeaders = smo.getHeaders().getMQHeader().getHeader();
//Create a new MQChainedHeaderType
MQChainedHeaderType chainedHeader = 
	ServiceMessageObjectFactory.eINSTANCE.createMQChainedHeaderType();
//Set the CCSID, encoding and format of the header
chainedHeader.setCodedCharSetId(1208);
chainedHeader.setEncoding(MQC.MQENC_INTEGER_NORMAL | 
                      MQC.MQENC_DECIMAL_NORMAL | 
                      MQC.MQENC_FLOAT_IEEE_NORMAL);
chainedHeader.setFormat(MQC.MQFMT_DEAD_LETTER_HEADER);
//Set the value of this header to be the MQDLH                     
chainedHeader.setValue(mqdlh);
//Add the chained header to the list of MQ headers
mqHeaders.add(chainedHeader);

out.fire(smo);			

This code only adds the MQDLH header to the MQHeaderType structure, not the MQMD. If no MQMD is specified when the message reaches the MQ import binding, then a default MQMD will be added. However, if an MQMD was added here, then the MQ import binding uses it instead of adding a default header.

Testing the module

Use the universal test client to test the module:

32. Right-click on MQCustomHeaderModule mediation component and select Test component.
33. The body of the message does not matter, so click Continue.
34. In the Deployment Location, window select WebSphere ESB Server and then click Finish.

The server will start and the application will be deployed and invoked. Once the component test is complete, you will see the invoke returned.

35. Using WebSphere MQ Explorer, right-click on the Send queue and select Browse Messages.
36. Double-click on the message and you will see the properties that were set in the mediation component:

Congratulations -- you have successfully created a mediation module that adds a custom MQHeader to a message.

Back to top

Download

Information about download methods

Resources

• Getting started with WebSphere Enterprise Service Bus and WebSphere Integration Developer
  This article introduces developers to the IBM WebSphere Enterprise Service Bus server and its accompanying tooling, WebSphere Integration Developer.
  
  
• Developing custom mediations for WebSphere Enterprise Service Bus
  This article introduces the use of custom mediations using the WebSphere Integration Developer V6 environment for WebSphere Enterprise Service Bus V6.
  
  
• Invoke Web Services with WebSphere MQ and WebSphere ESB
  This tutorial introduces the WebSphere ESB MQ bindings and uses a custom body data binding to read and write MQ messages.
  
  
• Invoking a Web Service using a JMS client
  This tutorial introduces the WebSphere ESB JMS bindings and shows how a JMS message can be used to invoke a Web Service.
  
  
• WebSphere ESB developer resources page
  Technical resources to help you use WebSphere ESB as a flexible connectivity infrastructure for integrating applications and services to support an SOA.
  
  
• WebSphere ESB product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere ESB information center
  A single Web portal to all WebSphere ESB documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere ESB.
  
  
• WebSphere ESB documentation library
  WebSphere ESB product manuals.
  
  
• WebSphere ESB FAQs
  Basic questions and answers about the new WebSphere ESB product and its relationship to other WebSphere products.
  
  
• WebSphere ESB support
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
• Redbook: Patterns: SOA Design Using WebSphere Message Broker and WebSphere ESB
  Patterns for e-business are a group of proven, reusable assets that can be used to increase the speed of developing and deploying e-business applications. This Redbook shows you how to use WebSphere ESB together with WebSphere Message Broker to implement an ESB within an SOA. Includes scenario to demonstrate design, development, and deployment.
  
  
  
  
• WebSphere Integration Developer developer resources page
  Technical resources to help you use the WebSphere Integration Developer IDE to render your existing IT assets as service components, encouraging reuse and efficiency as you build SOA-based integration solutions across WebSphere Process Server, WebSphere ESB, and WebSphere Adapters.
  
  
• WebSphere Integration Developer product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere Integration Developer information center
  A single Web portal to all WebSphere Integration Developer documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Integration Developer environment.
  
  
• WebSphere Integration Developer information roadmap
  Roadmap of articles and resources to help you with installation, migration, administration, development, troubleshooting, and understanding the underlying technology.
  
  
• WebSphere Integration Developer documentation library
  WebSphere Integration Developer product manuals.
  
  
• WebSphere Integration Developer support
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
  
  
• WebSphere MQ developer resources page
  Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  
  
• WebSphere MQ product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere MQ V7 trial download
  A no-charge trial download of WebSphere MQ V6. Includes limited online support for Windows® and Linux® installations at no charge during the trial period.
  
  
• WebSphere MQ V6 information center
  A single Web portal to all WebSphere MQ V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere MQ environment.
  
  
• WebSphere MQ documentation library
  WebSphere MQ product manuals.
  
  
• WebSphere MQ support page
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
• WebSphere MQ public newsgroup
  A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users.
  
  
• WebSphere MQ SupportPacs
  Downloadable code, documentation, and performance reports for the WebSphere MQ family of products.
  
  
  
  
• WebSphere SOA solutions developer resources page
  Get technical resources for WebSphere SOA solutions.
  
  
• developerWorks SOA and Web services zone
  Technical resources for evaluating, planning, designing, and implementing solutions that involve SOA and Web services.
  
  
• developerWorks WebSphere Business Integration zone
  For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
  
  
• WebSphere Business Integration products page
  For both business and technical users, a handy overview of all WebSphere Business Integration products
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Technical books from IBM Press
  Convenient online ordering through Barnes & Noble.
  
  
• developerWorks technical events and Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  
  

About the authors

Philip Norton is a software engineer at IBM Hursley Lab. He works on the WebSphere ESB Development team. His expertise includes Java and JMS for Websphere MQ. He is a certified Java Programmer and he has a degree in Computer Science from Canterbury University.

Alex Wood works at IBM Hursley Lab in England as a software developer for the IBM WebSphere Business Integration suite of products. He has extensive experience in development on many of the WebSphere products, including WebSphere MQ, WebSphere Message Broker, WebSphere Enterprise Service Bus, and WebSphere Process Server. He received a BSc in Physics with Astrophysics from Birmingham University in the UK in 1998.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Modeling the header
• Writing the Custom Header data binding
• Description of the data binding
• Using the Custom Header data binding in a mediation module
• Testing the module
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere MQ
• Webcast: A smarter way to successful SOA - Information as a trusted strategic asset
• Briefing: WebSphere flexible business processes for a smarter planet
• Buy: WebSphere MQ

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers