Chapter 9: Asynchronous Interoperability, Part 2: WebSphere MQ

In the previous chapter, we covered how Microsoft Message Queuing (MSMQ) 3.0 can be used to provide some level of asynchronous interoperability between .NET and J2EE. By using a custom API with XML Web services, we exposed some simple endpoints for sending messages to and retrieving them from an instance of MSMQ. We then looked at what this means in a production environment.

In this chapter, we'll look at IBM's message queue solution, WebSphere MQ. Throughout the chapter, we'll examine the support IBM has for both Java and .NET. In particular, we'll look at the Java Message Service (JMS) specification and see an example of how a Message Driven Bean (MDB) in J2EE can be modified to call a .NET Web service upon activation. The chapter concludes by discussing how mixing SOAP and the WebSphere MQ product can offer future options to achieve interoperability.

IBM WebSphere MQ

IBM's WebSphere MQ was more commonly known until recently as MQSeries; the name change applied with version 5.3 of the product. Throughout the chapter, we'll look at WebSphere MQ 5.3, covering the details of the product and then using it to provide interoperability between .NET and J2EE.

WebSphere MQ has evolved dramatically since it was first used as a message queuing product for IBM mainframes, and it is supported on more than 35 platforms today. More recently, IBM's focus has been to offer message queue integration for Java. This includes a full library for Java and support for the JMS specification.

Given the goal of demonstrating interoperability between .NET and J2EE, you might wonder why I chose the WebSphere MQ product for this chapter rather than a similar product from another vendor. My main reason for selecting WebSphere MQ is its position in the enterprise market. Three out of four businesses that use message queue implementations use WebSphere MQ (including MQSeries), and two- thirds of the top 100 North American and European banks use WebSphere MQ (source: http://www.ibm.com/mqseries ). Given this reach, I felt it was important to show options for how .NET, J2EE, and WebSphere MQ itself can interoperate in these types of enterprise environments.

Downloading and Installing

To allow evaluation of the product, IBM has a 90-day trial version of WebSphere MQ 5.3. This can be downloaded from http://www.ibm.com/mqseries and is supported on Microsoft Windows, AIX, Linux, Sun Solaris, and a number of other operating systems.

If you already have a copy of WebSphere MQ 5.3 and are familiar with the setup of the product, you can skip this section. This chapter's sample code, however, does assume that you're running WebSphere MQ on either Microsoft Windows XP Professional or Microsoft Windows Server 2003.

Once you've downloaded the evaluation version of the product, you must follow a number of steps to get an instance of WebSphere MQ up and running. The installation of WebSphere MQ is performed via a series of wizards, the first screen of which is shown in Figure 9.1.

Figure 9.1: Starting the evaluation installation of WebSphere MQ 5.3.

The first wizard prompts for a location to which you'll extract all the files required for installation. After the files are copied to this directory, a second installation wizard will be launched. After a short video (which can be skipped ), the installation launchpad will be displayed. Within the launchpad , check that the machine onto which you're installing WebSphere MQ has the correct prerequisites. These include a recent copy of a Java Virtual Machine (JVM) ” essentially , 1.3 or higher ”and a number of Windows components that are used by some of the administration tools. If you're using the Sun Java 2 Standard Edition (J2SE) 1.4.1, you might find that the launchpad doesn't recognize that the JVM has been installed. Despite this, when you run the sample code in this book, you should be able to proceed and ignore the warning messages.

In addition, WebSphere MQ will require details for the account to use for running the WebSphere MQ Windows Service. As the prompts suggest, it's advisable to check with your system administrator to find out the exact details here. These details are confirmed later in the installation process.

After validating the options in the launchpad, the final wizard (which installs the software) will be run. Read and accept the license agreement, and select a Custom installation. This will allow the selection of components that you'll need for the chapter's examples. Choose an installation location for the program, data, and log files; it's assumed for the examples that WebSphere MQ is installed in the default location.

Tip

When installing WebSphere MQ 5.3, if you do have an existing installation of MQSeries 5.2 on your machine, you might be prompted to upgrade. In all situations, I recommend following the custom option to ensure all the required components are installed.

Select all the available options, as shown in Figure 9.2.

Figure 9.2: Selecting all the installation options for WebSphere MQ.

Confirm the installation details in the next screen, and complete the wizard. WebSphere MQ is now installed.

After the installation has completed, a preparation wizard will be launched to allow you to prepare WebSphere MQ. This is used to configure network account information and verify the setup of the product. Within this wizard, either select Yes and enter the account details that you'll use for the WebSphere MQ service, or select No to configure the service to run as the SYSTEM account. Once given this information, the service will be configured and started.

After the Prepare WebSphere MQ Wizard has completed, you'll be presented with a list of next-step options. Clear all the options ”because we'll explore the tools together throughout this chapter ”and complete the installation.

Important

As with ASP.NET security, although using the SYSTEM account allows the samples in this book to work, this is not recommended in a production environment. Instead, you should create a dedicated user account and assign that account the minimal amount of privileges required. If you do plan to use the SYSTEM account, you should consult the WebSphere MQ documentation for security guidelines.

Configuring WebSphere MQ

After a successful installation, launch the WebSphere MQ Explorer. The Explorer can be found in the IBM WebSphere MQ Programs folder and is the main administration console for creating new queues and queue managers. As with the MSMQ administration tool, the WebSphere MQ administration tool runs as a Microsoft Management Console (MMC) snap-in. Figure 9.3 shows this tool.

Figure 9.3: The WebSphere MQ Explorer administration tool.

Your first task is to create a queue manager. Within WebSphere MQ, it's possible to logically group queues together under a queue manager. This queue manager allows resources and system options to be shared among the queues that are contained within WebSphere MQ.

To create a queue manager, right-click the Queue Managers folder in the left-hand pane and select the New/Queue Manager option. Create a queue manager named STQM (which stands for STock Queue Manager). This name and its casing are important for the samples that we'll run in this chapter. Also, it's important to make this the default queue manager, as shown in Figure 9.4. You don't need to specify a Default Transmission or Dead Letter Queue.

Figure 9.4: Creating a new queue manager and making it the default.

Accept the logging defaults in the next screen as part of step 2, shown in Figure 9.5, and, in step 3, ensure that the queue manager will be started once this creation step has been completed.

Figure 9.5: Setting the logging options for the queue manager.

Accept the defaults for the next screen, as shown in Figure 9.6. This configures the TCP/IP port settings for incoming connections. Port 1414 should be used for compatibility with the sample code.

Figure 9.6: Creating a TCP/IP listener for the queue manager.

The queue manager is now created. Returning to the MMC administration tool, you should see the default queue manager, STQM (shown in Figure 9.7).

Figure 9.7: Viewing the new queue manager in WebSphere MQ Explorer.

You'll find a folder named Queues under the STQM option in the tool. This folder is currently empty but will contain queues as you start to define them.

Note

Although the Queues folder is currently empty, creating the queue manager also created some system queues. These can be examined by right-clicking the Queues folder and selecting the View/ Show System Objects option.

To create a new queue, right-click the Queues folder and select New/ Local Queue. To show the samples using the same theme, let's create two new local queues, LOCAL.STOCKPURCHASES and LOCAL.STOCKSALES . For each of these queues, enter the queue name and queue description, as shown in Figure 9.8.

Figure 9.8: Creating a new queue named LOCAL.STOCKPURCHASES.

Ensure that the LOCAL.STOCKPURCHASES and LOCAL.STOCKSALES queue names contain no spaces. Feel free to browse through the options available for the local queue, but accept the defaults. Once complete, the two queues will be visible in the Queues folder of the queue manager, as Figure 9.9 depicts.

Figure 9.9: Viewing these queues in the WebSphere MQ Explorer.

Tip

You might be wondering why we're using uppercase names for the queue manager and queues. WebSphere MQ (and previous implementations of MQSeries) have a history of support for connecting to mainframes. Providing this support constrains the names that can be used. For example, a Multiple Virtual Storage (MVS) system connecting to WebSphere MQ has a limit of four characters that can be used for the queue manager. If we had chosen DefaultQueueManager as the name, connecting to MVS at some point in the future might have not been possible. (And renaming queue managers shouldn't be taken lightly ”renaming means that all queues need to be re-created.) In addition, general guidelines and experience dictate that we should follow a naming convention similar to that of other system queues that we'll work with throughout the chapter.

You now have your two queues created. The WebSphere MQ administration tool allows you to list any messages in the queues by double-clicking these items and supports placing a test message on the queue. To do this, right-click one of the queues and select Put Test Message. Enter some text in the window that appears, as shown in Figure 9.10, and press OK to submit the message to the queue.

Figure 9.10: Creating and sending a test message for one of the queues.

To clear the messages in a queue, right-click the queue and select the All Tasks/Clear Messages option. We'll now continue the installation and configuration by installing publish/subscribe support for the queues.

Installing Publish/Subscribe Support for WebSphere MQ

Publish/subscribe systems consist of producers of information (known as publishers ) which is sent to or collected by consumers (known as subscribers ). The publish/subscribe concept is also frequently known as pub/sub .

In WebSphere MQ, pub/sub is enabled by installing the MA0C SupportPac from IBM. This SupportPac, which can be downloaded from http://www.ibm.com/software/ts/mqseries/txppacs/ma0c.html , allows WebSphere MQ 5.3 to control the underlying queues required for pub/sub functionality. It's required for the samples presented in this chapter.

Note

What is a SupportPac? SupportPac is the IBM term for software that provides fixes or extends the functionality of an existing application. IBM offers four categories of SupportPacs. Category 1 applies to fee-based support. Category 2 includes freeware (and unsupported) fixes and additions. Category 3 is considered a product extension, and Category 4 is used for contributions from third parties.

Download the SupportPac (ma0c_ntmq53.exe) from this site and run it. Follow the simple setup program and ensure that the installation directory matches that of the previous WebSphere MQ installation. Although it's not required, I do recommend a reboot of the machine after installation has completed. This will help ensure that all environment variables are set correctly.

After the reboot and when the WebSphere MQ Service has successfully initialized (indicated by a green, upward- facing arrow in the System Tray), run the following command from the bin directory of the WebSphere MQ installation (default is C:\Program Files\IBM\WebSphere MQ\bin):

 strmqbrk -m STQM 

This command will configure our default queue manager (STQM) to handle pub/sub messages. After running the command, the following confirmation message is displayed:

 MQSeries Publish/Subscribe broker started for queue manager STQM. 

Note that the MQSeries Publish/Subscribe broker will need to be rerun after every reboot. With this in mind, you might want to add the command to a startup script or menu item.

Now navigate to the C:\Program Files\IBM\WebSphere MQ\Java\bin directory. From here, run the following command, exactly as shown:

 ..\..\bin\runmqsc.exe STQM < MQJMS_PSQ.mqsc 

This will execute a WebSphere MQ script that sets up the queues required for supporting the pub/sub mechanism in JMS. We'll cover this topic later in this chapter, but it's advisable to run this command at this stage.

If successful, the following message should be displayed at the end of the script:

 8 MQSC commands read. No commands have a syntax error. All valid MQSC commands were processed. 

The required pub/sub functionality has now been installed for WebSphere MQ.

You can validate this installation by running a predefined verification script supplied with WebSphere MQ. Within the same directory (C:\Program Files\IBM\WebSphere MQ\Java\bin), run the PSIVTRun batch file with the following parameters:

 psivtrun -nojndi -m STQM 

This script will create a connection, factory, session, and topic and will add a message to test the pub/sub elements. You don't need to be concerned about these terms now ”you need only know that a successful verification will be shown with a series of messages similar to the following:

 Creating a Connection Creating a TopicConnectionFactory Creating a Session Creating a Topic Creating a TopicPublisher Creating a TopicSubscriber Creating a TextMessage Adding text Publishing the message to topic://MQJMS/PSIVT/Information Waiting for a message to arrive [5 secs max]... Got message: JMS Message class: jms_text   JMSType:         null   JMSXDeliveryCount:1 A simple text message from the MQJMSPSIVT program Reply string equals original string Closing TopicSubscriber Closing TopicPublisher Closing Session Closing Connection PSIVT finished 

In the event that this isn't successful, WebSphere MQ should produce a reason code (for example, 2085). Running the command-line tool MQRC with the code will give some detail about the error. For example:

 C:\Program Files\IBM\WebSphere MQ\Java\bin>mqrc 2085 0x00000825  MQRC_UNKNOWN_OBJECT_NAME 

This error can then be traced and resolved by using the IBM WebSphere MQ documentation.

Congratulations, you have successfully installed WebSphere MQ. We can now investigate the libraries supplied by IBM, explore the chapter's sample code, look at the options available when using the product to pass messages, and achieve interoperability between the .NET and platforms.

WebSphere MQ Support for Java

IBM provides two sets of libraries that can be used with a Java environment. The first is an IBM-provided (vendor-specific) implementation. All the classes in these libraries fall within the com.ibm.mq.* package. The second is a JMS implementation of these libraries (which can be found in javax.jms.* ).

We'll start by looking at the IBM-provided libraries that can be accessed from a Java client because these map well to the classes that IBM also supplies for .NET.

To best demonstrate this Java library support, a sample has been created in the C:\Interoperability\Samples\Resource\WMQ\Simple\Java directory. This sample, shown in Figure 9.11, is similar to the MSMQ example illustrated in Figure 8-18 (on page 279), where a test message is written to the stock purchases queue and a message is read from the stock sales queue, if available.

Figure 9.11: Configuration for the supplied WebSphere MQ sample code.

The sample (Client.java) starts by first setting some variables that we'll use to access the WebSphere MQ implementation:

 String qmName = "STQM"; String purchasesQName = "LOCAL.STOCKPURCHASES"; String salesQName = "LOCAL.STOCKSALES"; 

These include the name of the queue manager and the two local queues that were defined.

Next, in the boundary of a try catch block, the queue manager is opened:

 MQQueueManager qmgr; qmgr = new MQQueueManager(qmName); 

This uses the MQQueueManager class within the com.ibm.mq package. In order to open queues within the queue manager, you need to first specify how the queues should be opened ”for example, whether a queue should be opened for reading messages, writing messages, or both. With the IBM libraries, the process of stating how to open a queue is done by passing specific constants as parameters when opening the queue.

For this example, you'll write to the stock purchases queue and read from the stock sales queue. The options required are as follows :

 int purchasesOptions      = MQC.MQOO_OUTPUT  MQC.MQOO_FAIL_IF_QUIESCING; int salesOptions      = MQC.MQOO_INPUT_AS_Q_DEF  MQC.MQOO_FAIL_IF_QUIESCING; 

The MQC.MQOO_FAIL_IF_QUIESCING option will cause the sample to throw an exception if the queue or queue manager is in the process of shutting down when the call is made. In order to open the queues, these options are passed with the queue name. First, the purchases queue is opened:

 MQQueue purchaseQ      = qmgr.accessQueue(purchasesQName,purchasesOptions); 

Once the queue is opened, a new message is created and placed on the queue. Part of this message creation process involves setting the encoding and character set:

 MQMessage msg = new MQMessage(); msg.writeString("This is a test purchase!"); msg.characterSet = 1208; purchaseQ.put(msg); purchaseQ.close(); 

Tip

To ensure compatibility between the Java and .NET samples, I recommend a character set of 1208 (which is UTF-8 encoding). This might change based on your environment and depending on the type of data that's being passed across the queue. A full list of supported character sets can be found at http://www.ibm.com/software/ts/mqseries/library/manualsa/csqzaw05/csqzaw0521.htm#TBLCSQ77T8 .

Now that you've placed the message on the queue, you need to open the sales queue to see whether any messages are waiting. The queue is opened with the options previously set:

 MQQueue salesQ = qmgr.accessQueue(salesQName,salesOptions); 

To retrieve a message, a new blank message is created. The get method from the queue is used to retrieve the message ”placing the data into the message that was created:

 MQMessage incomingMessage = new MQMessage(); salesQ.get(incomingMessage); 

If a message to be retrieved from the sales queue exists, the details (in this case, just the text of the message) are displayed to the console:

 System.out.println("Message:  "+incomingMessage.readString(incomingMessage.getMessageLength())); 

If no message is waiting to be collected, an exception of type com.ibm.mq.MQException will be raised. One of the fields of MQException is a reason code ”which is returned from WebSphere MQ to indicate what the problem is. Within the catch block of the sample, you check for reason code 2033 (no messages are in the queue) and display a suitable message based on this result:

 if (mqe.reasonCode == 2033) {     System.out.println("There are no messages awaiting collection"); } else {     mqe.printStackTrace(); } 

The sales queue is closed, and the queue manager is then disconnected.

Build and run the sample code using the provided Ant script. Type ant run from a command prompt in the C:\Interoperability\Samples\Resource\WMQ\Simple\Java directory. When both the purchases and sales queues are empty, the following should be observed :

 Test message has been placed on the purchase queue. MQJE001: Completion Code 2, Reason 2033 There are no messages awaiting collection. 

You've seen how the IBM libraries allow connectivity to an instance of WebSphere MQ from a Java application or service. Now let's look at the support available for .NET.

WebSphere MQ Support for .NET

To support .NET, IBM released a SupportPac in February 2003. This SupportPac (MA7P) is based upon an extended proof-of-concept written by a former IBM engineer in 2002.

At the time of this writing, this SupportPac is classed as Level 2. This means that IBM doesn't explicitly offer support for it. Although this classification might restrict organizations from using the SupportPac within production environments, the SupportPac is well suited for the sample code shown in this section.

To download the MA7P SupportPac, go to http://www.ibm.com/software/integration/support/supportpacs/individual/ma7p.html . Download and run the MA7P.MSI installer. Accept the defaults, which state that additional files will be installed to the C:\Program Files\IBM\WebSphere MQ\Tools\dotnet directory.

Note

At the end of the installation process, the MA7P SupportPac installer might issue a warning that it was unable to add the AMQMDNET.DLL to the global cache. This can easily be corrected by executing the following command from within the C:\Program Files\IBM\WebSphere MQ\bin directory:

 gacutil i amqmdnet.dll 

The MA7P SupportPac installs a AMQMDNET.DLL in the bin directory of the WebSphere installation. This DLL provides a set of classes that can be used with any .NET application. Although the classes are exposed as managed classes (using Intermediate Language, or IL), under the covers, the classes make PInvoke calls to other MQ client DLLs. This is important because any application that uses these classes will have a dependency on the WebSphere MQ client (or at least the underlying DLLs) installed on each machine.

Tip

What is PInvoke? PInvoke provides a direct way for managed code in .NET to call direct methods and functions in a Win32 DLL. Although this avoids using methods such as COM to achieve interoperability, managed code support (for example, garbage collection) isn't provided for these types of calls.

The classes that the AMQMDNET.DLL exposes are remarkably similar to the classes exposed in the Java environment. If, as a developer, you're either porting code between Java and .NET, or writing clients for each platform by using these classes, these matching APIs could be advantageous.

To complement the Java sample and to show these classes being used by a .NET client, a sample is included in the C:\Interoperability\Samples\Resource\WMQ\Simple\dotNET directory.

The client works in almost the exact same way as the Java classes. The classes exposed by AMQMDNET.DLL fall under the package IBM.WMQ , which is referenced at the top of the class:

 using IBM.WMQ; 

Each of the classes and methods exposed by the IBM.WMQ namespace uses the same names as the Java classes:

 MQQueueManager qmgr; qmgr = new MQQueueManager(qmName); int salesOptions      = MQC.MQOO_OUTPUT  MQC.MQOO_FAIL_IF_QUIESCING; int purchasesOptions      = MQC.MQOO_INPUT_AS_Q_DEF    MQC.MQOO_FAIL_IF_QUIESCING; 

Build and run the .NET sample code using the provided NAnt script (enter nant run at a command prompt). The script makes reference to the required AMQMDNET.DLL library for compiling. The location of this DLL is defined in C:\Interoperability\Samples\Config\webspheremq.nant.properties. If WebSphere MQ is installed in a location other than the default or if you have problems compiling, you should check the properties of this file.

Because the Java client sample has previously been run, you should observe the following output:

 Test message has been placed on the sales queue. Message:  This is a test purchase! 

The .NET client has placed a test message on the sales queue and picked up the message that the Java client placed on the purchases queue. If you now return to the Java client and rerun it, you should observe a similar behavior:

 Test message has been placed on the purchase queue. Message:  This is a test sale! 

While running these samples, you can use the IBM WebSphere MQ Explorer to view the messages as they're placed on the queue by each of the clients. As with the MSMQ examples earlier in the section, the administration tool lets you investigate the data of the message, as shown in Figure 9.12.

Figure 9.12: Viewing the message in WebSphere MQ Explorer.

This will become more useful as we continue to look at different message types in the following sections. As you can see in the figure, the text is passed between the Java and .NET clients in a "raw" format (meaning that it's not serialized or packaged in any way). The raw format that composes the message is literally a stream of bytes.

Differences Between the Java and .NET Classes

You saw earlier how to use the MA7P SupportPac to create a simple client application in .NET that has the ability to put messages to and get messages from an instance of WebSphere MQ. Creating the .NET client required classes and methods that were almost identical to their Java equivalents, allowing simple messages to easily be exchanged between them.

Unfortunately, not all the methods available in the Java classes are replicated in .NET. Today the MA7P SupportPac remains a subset of the classes that can be found in Java.

Looking through the documentation that accompanies the SupportPac, you can see that the following list of classes are available in Java but aren't present in the .NET version:

• MQChannelExit

• MQDistributionList

• MQDistributionListItem

• MQMessageTracker

• MQPoolServices

• MQPoolServicesEvent

• MQPoolServicesEventListener

• MQPoolToken

• MQProcess

• MQSimpleConnectionManager

• MQReceiveExit

• MQSendExit

• MQManagedConnection

• MQManagedConnectionFactory

• MQManagedConnectionMetaData

So, what is lost today with using the .NET MA7P SupportPac? MQDistributionList and MessageTracker are used by clients that need to send a single message to multiple queues. The MQPool classes are used for setting up a connection pool ”the .NET version supports only individual connection types. The ManagedConnection classes are supersets of existing connection classes and are used to provide additional data about the connection type.