Skip to main content

Using WebSphere MQ bindings in WebSphere ESB, Part 2: Creating MQ headers using the WebSphere ESB MQ Structures API

Philip Norton (nortonp@uk.ibm.com), Software Engineer, WebSphere ESB development team, IBM
Philip Norton photo
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 (wooda@uk.ibm.com), Software Developer, IBM United Kingdom
Alex Wood
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.

Summary:  WebSphere ESB and WebSphere Process Server enable conversion between message protocols such as SOAP and MQ. When a request message is received in SOAP, it does not contain the message headers required by WebSphere MQ. The WebSphere MQ binding can add the required headers automatically, but these headers are not configurable. This article shows you how to use the MQ structures Java API to add an MQ header from a custom mediation. It includes sample code for creating the MQ structures required by the WebSphere MQ binding.

View more content in this series

Date:  21 Jan 2009
Level:  Intermediate
Activity:  648 views
Comments:  

Introduction

IBM® WebSphere® ESB V6.0.2 introduced WebSphere MQ bindings, which let you send and receive messages via WebSphere MQ. The MQ binding automatically adds an MQ Message Descriptor (MQMD) to any messages that don't have one, but does not let you modify the MQMD. However, if the message already contains an MQMD, then the binding uses it instead of creating a new one. Therefore if an MQMD is created before the message reaches the MQ binding, you have a level of control over the content of the header.

With the introduction of the MQ bindings came a new API, enabling you to add an MQMD and you own headers to a message. You can use this API in a custom mediation to modify the Service Message Object (SMO) to include these MQ headers, thus ensuring that when the MQ binding receives the message, it does not create a new MQMD, but instead uses the existing one.

Software 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

Building the module

Start by creating a simple Library and Mediation Module in which to use custom mediation:

  1. Create a new Library called MQHeaderLibrary.
  2. Open the dependencies on the library, and under Predefined Resources, click Schema for simple JMS Data Bindings and click Save. This step makes the JMS body types available.
  3. In the Library, create a new interface named 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. Create a new mediation module named MQHeaderModule. Ensure that Create mediation component is ticked and click Next.
  7. Tick the MQHeaderLibrary and click Finish.
  8. Add an import to the assembly diagram.
  9. Wire the mediation component to the import, and when asked to add a reference, select MQBytesInterface.
  10. Right-click on Import1 and select Generate Binding => Messaging Binding => MQ Binding.
  11. Specify your queue manager name, send destination, host name, server channel, and port of your WebSphere MQ installation.
  12. Under Data Configuration, click Browse.
  13. Select the Show predefined data bindings radio button.
  14. Select MQ unstructured binary message, click OK, and then click OK again.
  15. Right-click on the mediation component, select Add => Interface, select MQBytesInterface, and then click OK.

Your module should now look like this:


Figure 1. MQHeaderModule
MQHeaderModule

Here is an explanation of the MQ data binding that has just been configured. The MQ unstructured binary message (com.ibm.websphere.sca.mq.data.impl.MQDataBindingImplXML) data binding reads and writes the MQ message body as a byte array. It does not attempt to parse the body, and therefore has no understanding of the structure. The data binding requires an input type of JMSBytesBody business object, which contains a single hexbinary value. Do not get confused by the use of JMSBytesBody with an MQ binding, as there is an unstructured binary data binding for JMS, and the JMSBytesBody is just reused from there. You can use this data binding only if no work is to be performed on the message body. The advantage of using the data binding is that you can add and modify message headers without the module having to parse the body of the message, resulting in a performance gain.

Building the mediation flow

Next, create the mediation flow and use the MQ structures API to add an MQ header:

  1. Double-click on the mediation component MQHeaderModule to generate an implementation.
  2. In the Mediation Flow Editor, wire operation1 to operation1 to create a flow.
  3. In the Palette, select Transformation => Custom Mediation.
  4. Add the custom mediation to the canvas.
  5. Wire the input node to the input terminal of the custom mediation.
  6. Wire the output terminal of the custom mediation to the callout node.

Your mediation flow should now look like this:


Figure 2. MQHeaderModule Mediation Flow
MQHeaderModuleMediationFlow

  1. On the Properties panel of the custom mediation, select the Details tab.
  2. Click the Java radio button.
  3. Replace the content with the code in Listing 1:

Listing 1. Custom Mediation Code for Adding MQ Header
          
//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);
}

//Retrieve the MQMD from the MQHeader
MQMD mqmd = smo.getHeaders().getMQHeader().getMd();
//If there is no MQMD
if (mqmd == null) {
	//Create a new MQMD structure
	mqmd = WMQStructuresFactory.eINSTANCE.createMQMD();
	//Set it in the MQHeader
	smo.getHeaders().getMQHeader().setMd(mqmd);
}
mqmd.setExpiry(300000);
mqmd.setMsgFlags(MQC.MQMF_SEGMENTATION_INHIBITED);
mqmd.setPersistence(MQC.MQPER_PERSISTENT);
mqmd.setPriority(8);

//Retrieve the MQControl from the MQHeader
MQControl mqControl = smo.getHeaders().getMQHeader().getControl();
//If there is no control
if (mqControl == null) {
	//Create the MQControl structure.  This describes the format of the message body
	mqControl = WMQStructuresFactory.eINSTANCE.createMQControl();
	//Set it in the MQHeader
	smo.getHeaders().getMQHeader().setControl(mqControl);
}
//Set CCSID to UTF-8
mqControl.setCodedCharSetId(1208);
//Set encoding to big endian
mqControl.setEncoding(MQC.MQENC_INTEGER_NORMAL | 
                      MQC.MQENC_DECIMAL_NORMAL | 
                      MQC.MQENC_FLOAT_IEEE_NORMAL);
//Set format to none
mqControl.setFormat(MQC.MQFMT_NONE);

out.fire(smo);

  1. Select the Java Imports tab, enter the content of Listing 2, and save the mediation component:

Listing 2. Custom Mediation Imports

import com.ibm.websphere.sibx.smobo.MQHeaderType;
import com.ibm.websphere.sca.mq.structures.MQMD;
import com.ibm.websphere.sca.mq.structures.MQControl;
import com.ibm.websphere.sca.mq.structures.MQHeaders;
import com.ibm.websphere.sca.mq.structures.WMQStructuresFactory;
import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
import com.ibm.mq.MQC;

Code description

The diagram of the MQHeader SMO structure shown below in Figure 3 helps explain the code shown above in Listing 1. The top-level type MQHeaderType is an SMO element, so it is created using the ServiceMessageObjectFactory. This type contains a single MQMD, an MQControl type, and a MQChainedHeaderType. The MQMD and MQControl are MQ structure types, so you create them using the WMQStructuresFactory:

  • MQMD describes the MQ message descriptor that will be added to the message.
  • MQControl describes the formatting used for the message body.

The MQChainedHeaderType is an SMO element that allows additional MQ headers to be added to the message. It isn't used in this article, but Part 3 uses it to add a custom header to an MQ message.


Figure 3. MQHeader Structure
MQHeaderStructure

When creating an MQMD and setting its fields, keep in mind:

  • For information on valid field values, see Using Java in the WebSphere MQ Information Center.
  • Any fields that are not set will automatically be set to the default value for that field.
  • Some fields will be overwritten when the message is sent to MQ, including:
    • MsgType
    • MsgID
    • BackoutCount
    • ReplyToQ
    • ReplyToQMgr
    • UserIdentifier
    • AccountingToken
    • ApplIdentityData
    • PutApplType
    • PutApplName
    • PutDate
    • PutTime
    • ApplOriginData
    • GroupId
    • MsgSeqNumber
    • Offset
    • OriginalLength

Testing the module

Use the universal test client to test the module:

  1. Right-click on the MQHeaderModule mediation component and select Test component.
  2. The body of the message is not important, so click Continue.
  3. In the Deployment Location window, select WebSphere ESB Server and click Finish.

The server will start and the application will be deployed and invoked. After the component test is complete, you will see the invoke returned, as shown below:


Figure 4. Invoke Returned
MQHeaderTestComplete

  1. Using WebSphere MQ Explorer, Right-click on the Send queue and select Browse Messages.
  2. Double-click on the message and you will see the properties set in the mediation component, as shown in Figure 5:

Figure 5. MQMessage
MQMessage

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


Back to top

Download

DescriptionNameSizeDownload method
Project Interchange containing MQHeaderModulePIMQHeaderModulePI.zip14KBHTTP

Information about download methods


Resources

About the authors

Philip Norton photo

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

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

Back to top

Trademarks  |  My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=365985
ArticleTitle=Using WebSphere MQ bindings in WebSphere ESB, Part 2: Creating MQ headers using the WebSphere ESB MQ Structures API
publish-date=01212009
author1-email=nortonp@uk.ibm.com
author1-email-cc=ramaker@us.ibm.com
author2-email=wooda@uk.ibm.com
author2-email-cc=

Table of contents

Next steps from IBM

My developerWorks community

Interact, share, and communicate with developers worldwide.

My developerWorks overview

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).

My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

 

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Rate a product. Write a review.

Write a review for Rational products today!

Special offers

Rate and Review Rational products

WebSphere Application Server Hypervisor trial

SOA Tutorials IBM Book + DVD 35% off: IBM0402

More offers