Skip to main content

skip to main content

developerWorks  >  WebSphere  >

Enabling SCA-MQ integration via MQ bindings

developerWorks
Document options

Document options requiring JavaScript are not displayed

Sample code


Rate this page

Help us improve this content


Level: Intermediate

Benedict Fernandes (bxf@us.ibm.com), Senior Managing Consultant, IBM Software Services for WebSphere, IBM　
José De Jesús (jdejesus@us.ibm.com), IBM Certified IT Architect, IBM Global Account team, IBM

06 Feb 2008

The MQ Bindings feature in WebSphere Integration Developer V6.0.2, simplifies interoperability between SCA and MQ applications, and makes it easier to read and write native MQ messages to and from SCA applications.

Introduction

Service Component Architecture (SCA) applications are typically developed to functionally integrate existing enterprise resources. Many existing legacy applications are based on messaging technologies such as IBM® WebSphere® MQ. The MQ Bindings feature, introduced in WebSphere Integration Developer V6.0.2, simplify interoperability between SCA and MQ applications, and make it easier to read and write native MQ messages to and from SCA applications. This article describes MQ Bindings, then shows you how to create an end-to-end solution based on SCA and MQ legacy applications.

Basic concepts

SCA Applications are housed in a WebSphere Integration Developer container-like abstraction called an SCA module, which typically contains business objects (BOs), interfaces, exports, and imports:

  • Business objects are user-defined data types, represented internally as XML in Service Data Object (SDO) format.
  • Interfaces represent the client contract and specify the inputs to and outputs from the service.
  • Exports and imports are SCA abstractions that enable an SCA application to interoperate with the outside world.

For an SCA component to communicate with messaging-based applications over message queues, its exports and imports must be configured with SCA messaging bindings. SCA supports three types of messaging bindings:

  • Java Messaging Service (JMS) binding -- Used typically by pure JMS clients such as those that use the WebSphere default messaging provider.
  • MQ JMS binding -- Used typically by JMS clients that use WebSphere MQ as the underlying messaging provider.
  • MQ binding -- Used typically by pure MQ clients, also called legacy MQ clients.

This article focuses on showing you how to use the MQ Binding.

An Export - MQ binding is used when you want your component accessed in an asynchronous manner from a WebSphere MQ messaging client. An Import -- MQ binding is used when you want to access the WebSphere MQ Messaging Provider from a component.

Data binding is another important term. The main function of a Data Binding class is to bridge data formats that correspond in some way to the schema of an input or output message. In this case, our Data Binding class transforms the data passed in the native format from a messaging system to a Service Data Object (SDO) in an SCA application and vice-versa for a response message. The Data Binding class implements a predefined interface and is configured as part of the Export or Import at the boundaries of an SCA application. It also typically instantiates and populates a business object. WebSphere Integration Developer and WebSphere Process Server currently only support Java as the implementation language for Data Binding classes.

End-to-end application scenario


Figure 1
Figure 1
  1. An MQ messaging client puts a message on an MQ local queue, EXPORTQ. The RFHUTIL utility is used as both the message producer and consumer.
  2. The arrival of a message in EXPORTQ causes the SCA Export configured with MQ Messaging Bindings to consume the message and invoke a BPEL process.
  3. The Data Binding class reads the native MQ message, parses it, and populates a business object of a previously defined type with that data.
  4. As part of its processing, the BPEL invokes an asynchronous MQ-based service.
  5. The SCA Import configured with MQ Messaging Bindings serializes the business object as an XML string, and puts it on a local MQ queue called IMPORTQ.
  6. The consuming MQ application, in this case RFHUTIL, can then consume the message.

Data

This example uses a 70-byte fixed length flat text message with the following structure:


Figure 2
Figure 2

It is important to understand the native data format you are working with so that you can make the right architectural decisions as to where to allocate the work in your application. For example, your application may require parsing the raw data after it reaches the BPEL part of the code instead of in the Data Binding class.

The following sections walk you through the detailed steps required to implement the above scenario. To help you better understand the overall structure and sequence of tasks, here are the steps involved:

  • Create WebSphere MQ resources: queue manager and queues
    • Create WebSphere MQ queue manager
    • Create WebSphere MQ queues
    • Create WebSphere Process Server-based business application -- implement BPEL business logic
    • Create BI module (container for all SCA artifacts)
    • Create business objects
    • Create service interfaces
    • Create BPEL process
    • Create messaging-related SCA artifacts: exports, imports, data binding
    • Create Data Binding class
    • Create SCA messaging export
    • Create SCA messaging import
  • Test application from end-to-end
  • Use RFHUtil to send and monitor messages

Create WebSphere MQ resources

The MQ resources required for this example include an MQ queue manager named QMGR900 with its listener port configured on Port 1490, and two MQ local queues named EXPORTQ and IMPORTQ. Use the WebSphere MQ Explorer utility to create the required MQ resources. After you have created the EXPORTQ and IMPORTQ local queues, the view of WebSphere MQ Explorer should look like this:


Figure 3
Figure 3

If you need detailed instructions on creating the MQ resources, see the file <download_root>/MQBindings/docs/MQResourcesSetup.doc, which you can download below.

Create WebSphere Process Server BPEL-based application

From within the Business Integration perspective, create a new module to house the artifacts required by this application. To switch to the Business Integration perspective, select Window => Open Perspective => Business Integration. In the Business Integration view, right-click on the canvas and select New => Module. In the New Module panel, enter MQBindings in the Module Name field and click Finish.

In the Business Integration perspective, expand MQBindings, right-click on Data Types and select New => Business Object. Create the ProcessBO business object in the /com/ibm/issw folder as shown below, and click Finish:


Figure 4
Figure 4

This opens the Business Object Editor. Click Add Attribute to create a single String attribute called orderString:


Figure 5
Figure 5

This field will contain the entire native WebSphere MQ incoming message as a fixed-length string. The incoming message could have a different format. Click Ctrl+S to save.

Repeat the steps above to create an additional business object called ServiceXBO in the same /com/ibm/issw folder as you did for the ProcessBO business object above. Here are the required attributes for ServiceXBO:


Figure 6
Figure 6

Click Ctrl+S to save. Now that the Business Objects are created, you can create the service interfaces that will be used by the BPEL process. In the navigation tree, expand MQBindings => New => Interfaces. Right-click Interfaces to launch the New Interface panel. Enter the interface name and its respective folder/package as shown below, and click Finish:


Figure 7
Figure 7

In the Interface Editor, add a one-way operation called processOrder. Modify the field name to orderInput, and select its associated type as ProcessBO as shown below. Click Ctrl+S to save:


Figure 8
Figure 8

Create a new service interface called ServiceXInterface in the com/ibm/issw folder similar to the way you did in the previous step. In the Interface Editor, add a one-way operation called updateInventory. Modify the field name to orderInput, and select its associated type as ServiceXBO. Click Ctrl+S to save:


Figure 9
Figure 9

Now you can create the BPEL process that will handle the incoming message and put it on an outgoing queue. From the Business Integration perspective, create a new business process: expand MQBindings => Business Logic, right-click Process, and select New => Business Process.

Create a new BPEL process called OrderProcess in the com/ibm/issw folder as shown below, then click Next:


Figure 10
Figure 10

Click Select an existing Interface and click Browse to search and select the OrderProcessInterface. The processOrder operation is automatically selected. Click Finish.

In the Business Process Editor, add a Java snippet: select the Snippet activity and change the default Java snippet name to Log Input. In the Properties View, click the Details tab and select Java as the implementation type. If the Question dialog appears, click Yes. In the text area, enter the following line of code:

System.out.println("The Input Order Record is ==> " + OrderInput);

The resulting BPEL should look like this:


Figure 11
Figure 11

As in the steps above, add another Java snippet node and change its name to Prepare Service Call. Cut-and-paste the code for this Java snippet from the provided text file: <download_root>/MQBindings/code/PrepareServiceCallX-codeSnippet.txt.

To handle the compilation errors that appear, right-click inside the Snippet window and select Source => Organize Imports.To resolve the compilation errors, select the following packages: commonj.sdo.DataObject, com.ibm.websphere.sca.sdo.DataFactory.

This code snippet uses a temporary variable, the ServiceXBO, that is used to hold the input to invoke ServiceX. The snippet uses basic Java string manipulation techniques to extract the relevant data from the original incoming message and then populates a BO that is ServiceX-specific:


Figure 12
Figure 12

To resolve the remaining compilation errors, create the theServiceXBO temporary variable and associate it with the appropriate data type. From within the BPEL Editor outline view, click the + sign in the Variables section and name the variable theServiceXBO:


Figure 13
Figure 13

In the Properties view, make sure that theServiceXBO appears as the associated data type. The resulting BPEL should look like this:


Figure 14
Figure 14

Next, add an Invoke activity to the BPEL process and rename it Invoke ServiceX for clarity. The Invoke activity must be configured to invoke or call out to a service. The respective invoked service interface, also called Reference Partner, must be configured. To do so, drag-and-drop the ServiceXInterface from the Navigation view onto the BPEL Process Editor canvas:


Figure 15
Figure 15

The above drag-and-drop action should result in the ServiceXInterface being added under the Reference Partners section.

In the Properties view, select the Details tab, then click Browse and select ServiceXInterface. Ensure that updateInventory is selected as the requested operation. Select the Use Data Type Variables checkbox, and select the temporary variable theServiceXBO. The resulting configuration should look like this:


Figure 16
Figure 16

As a final step in the BPEL process creation, add a simple Java snippet node to log an exit message. Rename it as Log Final. With the Log Final node selected, type in the following Java code:

System.out.println("Exiting OrderProcess Done -- BYE");

Your final BPEL process should look like this:


Figure 17
Figure 17

Create messaging-related SCA artifacts

To create the Data Binding class, switch to the Java perspective: select Window => Open Perspective => Other => Java => OK. From within the Package Explorer view, right-click on com.ibm.issw and select New => Class. Fill out the New Java Class panel by entering the name of the Data Binding class: InventoryCustomDataBinding. Then click Finish.

In the previous step, during class creation you could have indicated that this class implements the MQBodyDataBinding class. But for simplicity, a separate source file is provided that contains the complete MQ Data Binding class implementation. Open the text file <download_root>/code/InventoryCustomDataBinding.java in a text editor and replace the skeleton implementation in your workspace with the provided Java implementation. The methods specified on the MQBodyDataBinding class should appear in the outline view. Review the list of imports to get an idea of the underlying WebSphere Process Server packages used. ClickCtrl+S to save.


Figure 18
Figure 18

Switch back to the Business Integration perspective and from the Navigation view, select MQBindings => Business Logic => Process => OrderProcess. Drag-and-drop the OrderProcess component onto the canvas as shown below:


Figure 19
Figure 19

Select the OrderProcess component, right-click and select Generate Export => Messaging Binding => MQ Binding.

Configure the newly generated MQ Export via the MQ Export Binding panel. There are two main categories of configuration information required: WebSphere MQ configuration information and Data Binding class specification. The WebSphere MQ information, such as queue manager name, host, channel, and port should correspond to the queue manager settings configured earlier. In a production environment this would be obtained from the WebSphere MQ administrator. In this example, since this is a one-way communication flow, you need to specify only a Receive Destination Queue. This is the queue over which the internal SCA MDB would listen on and then deliver messages to the associated SCA component after the optionally configured Data Binding class is invoked.

As a final step in configuring the MQ Export, the properties for the data transformation section must be populated. Set the value for Request SerializationType to User Supplied from the pull-down menu. Then click Browse and select the InventoryCustomBinding class. The final configuration should look like this:


Figure 20
Figure 20

ClickOK to complete the configuration of the MQ Export. The newly created MQ Export appears on the Assembly diagram. Rename the MQ Export to OrderProcessExport:


Figure 21
Figure 21

Recall that SCA exports and imports are external access points for an SCA application. In the previous step, you configured the SCA Export with MQ messaging bindings, thus enabling the application to receive messages (inbound) from an MQ-based messaging client. You now need to configure an outbound communication path to enable the SCA application to send an asynchronous message to an MQ-based messaging client.

From the panel of icons, select an Import, drop it onto the canvas, and rename it to ServiceXImport. With the ServiceXImport selected, click the Interface icon that appears above it to add a new interface. From the Add Interface panel, select the ServiceXInterface. Recall that ServiceXInterface was configured at the beginning, after the business objects were defined. Click OK. Right-click on the ServiceXImport component and select Generate Binding => Messaging Binding => MQ Binding.

Configuring an MQ Import is similar to configuring an MQ Export, with two major tasks: configuring the MQ transport-specific information, and specifying the data transformation-specific information.

Enter the properties for the MQ Import as shown below. In this example, you simply serialize the business object and send it to the configured output queue, IMPORTQ in this case. Therefore, select Serialized as XML as the desired Request Serialization type, and click OK when done:


Figure 22
Figure 22

In the Assembly Diagram tab, select the wire from the OrderProcess component and connect it to the ServiceXImport. The final version of the assembly diagram with all wired components should now appear:


Figure 23
Figure 23

Test the application end-to-end

You are now ready to deploy the application to WebSphere Process Server. On the Servers tab, right-click on WebSphere Process Server V6 and select Add and remove projects. To deploy the application, click MQBindingsApp, then select Add => Finish, and wait for server status to change to Started. As usual, monitor the Server Console for any potential startup errors. You are now ready to test the application.

To start the testing process, use the MQ resources that were created earlier. You will use the RFHUTIL utility program to read a file from a text file and send the data as a message to the EXPORTQ local queue managed by the queue manager QMGR900. The arrival of a message on the EXPORTQ queue will get the BPEL process activated to consume the message. During its execution, the BPEL process will invoke an asynchronous service by placing another message on an outgoing MQ queue called IMPORTQ.

Start the RFHUTIL utility program. Point at queue manager QMGR900 and the EXPORTQ queue as shown in Steps 1 and 2 below. Then click Read File and point to the directory where you unzipped the data.txt file supplied with this article. Click Write Q to have the message delivered to the EXPORTQ:


Figure 24
Figure 24

You can also inspect the data by viewing the contents on the Data tab of the RFHUTIL screen. As explained before, putting a message on the EXPORTQ queue results in the message being consumed by the BPEL process, transformed, and delivered to the IMPORTQ queue. Every time you put a message on the EXPORTQ queue, the number of messages on the IMPORTQ queue should increase by one. To examine the queue depth of IMPORTQ and EXPORTQ, use the WebSphere MQ Explorer: Click Start => WebSphere MQ => WebSphere MQ Explorer and examine the Current queue length field as shown below. You can also inspect the data by viewing the contents on the Data tab of the RFHUTIL screen and viewing the serialized XML data message on the IMPORTQ.


Figure 25
Figure 25

You may examine the contents of the message on the IMPORTQ using the RFHUTIL utility as indicated below. Ensure that QMGR900 is selected as the queue manager, and IMPORTQ is selected as the current queue. Click Read Q to read a message from the queue. It causes the message to be physically deleted from the IMPORTQ.


Figure 26
Figure 26

To examine the actual contents of the message, select the Data tab and then select the XML button, since the SCA Import was configured with the Serialize as XML option, causing the message output to be transmitted as XML to the destination queue.


Figure 27
Figure

Conclusion

This article described the concepts behind the WebSphere Integration Developer V6.0.2 MQ Bindings feature, and then showed you the implementation steps and artifacts required to enable integration between SCA and MQ applications.

Acknowledgements

The authors would like to thank Peter Xu, Debasish Banerjee, and Robert Drelles for their valuable feedback.




Back to top


Download

DescriptionNameSizeDownload method
Code sampleMQBindingsArticleArtifacts.zip234 KBHTTP
Information about download methods


Resources



About the authors

Benedict Fernandes is a Senior Managing Consultant with IBM Software Services for WebSphere in Research Triangle Park, NC. He holds an MS in Information Networking from Carnegie Mellon University, an MS in Computer Science from De La Salle University, and an MSc (Tech) from BITS-Pilani, India. You can contact Benedict at bxf@us.ibm.com.


José De Jesús is an IBM Certified IT Architect on the IBM Global Account team in Boca Raton, FL. He holds a BS degree from Fordham University in New York, and an MBA with a specialization in Management of Technology from the University of Miami, FL. You can contact José at jdejesus@us.ibm.com.




Rate this page


Please take a moment to complete this form to help us better serve you.



YesNoDon't know
 


 


12345
Not
useful		Extremely
useful
 


Back to top