IBM WebSphere MQ

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

14.2 IBM WebSphere MQ

14.2.1 Introduction

HydraExpress supports a message queue transport that uses IBM WebSphere MQ.

The IBM WebSphere MQ transport is used like any other transport in HydraExpress, and can be easily integrated into your existing applications. Your code will function as before, except that messages will be sent using the specified MQ queue instead of the default HTTP protocol.

Using the MQ transport is easy and requires no changes to the WSDL or your applications.

This section includes the following topics:

Configuring WebSphere MQ for Use with HydraExpress
Configuring your MQ Transport and Listener
Using IBM MQ on the Client
Using IBM MQ on the Server

14.2.2 Configuring WebSphere MQ for Use with HydraExpress

Before using HydraExpress with WebSphere MQ, you need to set your MQ environment and create a queue in WebSphere MQ for each service inHydraExpress that will use an MQ transport.

To set your environment,

On Solaris, AIX, and Linux, add the MQ lib directory path to LD_LIBRARY_PATH.

On HP-UX, add it to SHLIB_PATH.

On Windows, add it to the PATH.

The MQ transport SDK has a dynamic dependency on the WebSphere MQ client libraries, so you must have the IBM WebSphere MQ client installed on your system. For WebSphere MQ client specific version information, please refer to HydraExpress README located in your top-level installation directory.

To create a queue in WebSphere MQ, see your IBM WebSphere MQ documentation.

Note for Linux Users

On Linux, IBM MQ libraries require the C++ Standard Library version libstdc++.so.3. HydraExpress, however, depends on the GNU C++ compiler version g++ 3.2, which comes with a more recent version of C++ Standard Library, libstdc++.so.5.

If you don't have the standard library version libstdc++.so.3, you will either have to install it, or make a symbolic link named libstdc++.so.3 that points to libstdc++.so.5. Both approaches work.

14.2.3 Configuring your MQ Transport and Listener

Configure your MQ transport in your transport configuration file (the default is server-transports.xml) and your client transport configuration file (default, client-transports.xml), using the properties in this section. See Section 14.2.4 and Section 14.2.5 for specifics on using an MQ transport in your client or service.

To configure your MQ transport for all services, edit the template files in the <installdir>\conf\webservices directory; otherwise, edit only the project configuration files.

Table 8: IBMMQ Transport and Listener Properties

Property name	Required	Value	Description
Applicable to Transports and Listeners
`serverQueue Name`	YES	string	Name of the queue on which the service receives messages
`queueManager`	YES	string	Name of the queue manager
`channelDef`	YES	string	MQ channel definition
Listener-specific
`timeout`	NO	integer	Specifies (in milliseconds) the `MQGET` timeout, after which the listener returns from `MQGET`, checks for stop signal, and if it has not received one, calls `MQGET` again. The default value is 1000. (one second). Note that this value affects the time it takes the listener to stop.
`auto-start`	NO	`true`/ `false`	Specifies whether the listener should be started automatically. Should be set to true for listeners that are hosted by the HydraExpress Agent.
Transport specific
`replyQueue Name`	NO	string	Name of the queue on which the transport expects a reply from the listener. Usually not specified, in which case a dynamic queue is created.
`sendSoap Action`	NO	`true`/ `false`	Specifies whether the transport should send SOAP action along with the message. Default is "`true`". Note: For document style services implemented in HydraExpress, this must be set to "true". For RPC style this is not required.
`timeout`	NO	integer	The amount of time the transport waits for the response from the listener in request/response style calls. Default is `MQWI_UNLIMITED`, which means the client blocks forever.

Only the transport-specific properties sendSoapAction and timeout may be modified between calls to invoke().

14.2.4 Using IBM MQ on the Client

To illustrate how to use the WebSphere MQ transport on the client side, we'll use the existing example DayofWeek in the directory <installdir>\tutorials\webservices\DayofWeek.

To use the IBM MQ transport on the client side:

Generate code as always.
Define an IBM MQ transport in your transport configuration files (server-transports.xml and client-transports.xml).
Edit your client to point to a default IBMMQ transport, or to allow the selection of an MQ transport at runtime.
Compile and run the application.

These steps are covered in more detail in the next sections.

14.2.4.1 Generate Code

From a command prompt, navigate to the directory <installdir>\tutorials\webservices\DayofWeek, and generate code. For this example, use the -projectname option to create a project called mq:

<prompt> rwsfgen -projectname mq example-project.xml

The additional option -projectname forces the code generator to override the project name identified in the example-project.xml file, therefore generating code into a code generation directory mq. The example-project.xml file is a HydraExpress project file that tells the generator to generate code using the DayOfWeek.wsdl as well as some other standard options. For more information on code generation and generated files, see Section 21.4, "Invoking the Generator with a WSDL File."For more information on creating a client and server using this DayofWeek example, see Chapter 8, "Developing Services."

14.2.4.2 Define an IBM MQ Transport in server-transports.xml

The generated code includes a transports configuration file server-transports.xml. Each transport configuration file contains a commented code block where the MQ transport properties are defined. These properties are originally set in your IBM WebSphere MQ installation.

The required MQ properties are:

the queue name
the queue manager
the channel

Following is the MQ transport code from the DayofWeek generated client-transports.xml.

<!-- Example IBM Websphere MQ Transport Definition
  <rwsf:transport name="IBMMQ"
    uri="http://schemas.xmlsoap.org/soap/mq" scheme="ibmmq"
    default="true" class="rwsf_webservice_transport_ibmmq.createIBMMQTransport">
      <rwsf:property name="auto-start" value="false"/>
      <rwsf:property name="protocol" value="mq"/>
      <rwsf:property name="serverQueueName"
        value="rwsf.MYSERVICE.QUEUE"/>
      <rwsf:property name="queueManager" value="QM_beaver"/>
      <rwsf:property name="channelDef"
        value="SYSTEM.DEF.SVRCONN/TCP/localhost"/>
      <rwsf:property name="sendSoapAction" value="true"/>
  </rwsf:transport>
  -->

To define an MQ transport, uncomment the code block, and enter values for serverQueueName, queueManager, and channelDef, according to your IBM WebSphere MQ settings.

14.2.4.3 Edit your Client

One way to allow your client to choose at runtime an alternate or custom transport such as MQ is to add these optional arguments to your client. Here's an excerpt from main() in the provided client implementation DayOfWeekPortClient.cpp located in the DayofWeek directory. This provided example includes two additional options for selecting a transport.

int main(int argc, char* argv[])
{
  
//generated comments removed

  std::string location;
  std::string transportName;                                //1

  if (argc < 2) {
    location = "http://localhost:8090/dayofweek/DayOfWeek";   
  }
  else if (argv[1][0]=='-' && argv[1][1]=='a') {
    location = "http://localhost:8013/dayofweek/DayOfWeek";
  }
  else if (argv[1][0]=='-' && argv[1][1]=='t') {              //2
    if (argc == 3) {
      transportName = argv[2];
    }
  }
  else if (argv[1][0]=='-' && argv[1][1]=='q') {              //3
  transportName = "IBMMQ"; 
  // use default MQ transport, named IBMMQ                
  }
  else if (argv[1][0]=='-' && argv[1][1]=='l') {
    location = "http://localhost:8090/dayofweek/DayOfWeek";
  }
  else {
    location = argv[1];
  }

  try {
    // initialize config files
    rwsf::HandlerManager::loadConfiguration("client-handlers.xml");
    rwsf::TransportManager::initialize(
         "client-transports.xml","2012d");

    DayOfWeekBindingProxy proxy;
    if (transportName.isNull()) {
      proxy = DayOfWeekBindingProxy::make(location);
    }
    else {
      rwsf::Transport transport =                              //4
          rwsf::TransportManager::findTransport(transportName);
      transport.setProperty("location",location);
      proxy = DayOfWeekBindingProxy::make(transport);
    }

`//1`	Declares a string to hold a transport name. For arguments `-t` and `-q` below, this object will be assigned the value of either a custom transport name or "`IBMMQ"`.
`//2`	Additional command line option `-t`. This option allows you to specify any transport configured in the `client-transports.xml` file, using the transport's `name` attribute as the `transportName`.
`//3`	Additional command line option `-q`. This option is used to select the default MQ transport defined in `client-transports.xml`. While you could also use the `-t` option and select the IBMMQ transport by name, this option is faster and easier when you plan to use the default IBMMQ.
`//4`	Alternatively, if you wish to set the default transport for this client to IBMMQ, you could select it in your client by passing the string "IBMMQ" to the `findTransport()` method, as follows: rwsf::TransportManager::findTransport("IBMMQ"); This way, you could run the client with no options.

For more information on setting up alternate and custom transports, see Chapter 11, "Dynamic Transports."

14.2.4.4 Compile and Run the Application

Run the client in one of the following three ways:

To run the client with a custom IBMMQ transport "MyCustomMQTransport" that you defined in client-transports.xml, navigate to the mq\bin directory, and enter

<prompt>  DayofWeekPortClient -t MyCustomMQTransport

To run the client with the default IBMMQ transport IBMMQ defined by HydraExpress in client-transports.xml, enter

<prompt>  DayofWeekPortClient -q

To run the client with a hard-coded IBMMQ transport entered as a parameter to the rwsf::TransportManager.findTransport()method (whether the default or not in client-transports.xml), enter

prompt>  DayofWeekPortClient                    //no options

14.2.5 Using IBM MQ on the Server

To use the IBM MQ transport on the server side, perform the same steps as for the client, except define a listener instead of a transport in server-transports.xml. There are no command line options when running the service.

14.2.5.1 Define an IBM MQ Listener in the Service server-transports.xml

To define the listener, edit the code block that defines the MQ Listener, as shown below:

<!-- Example IBM Websphere MQ Listener Definition
  <rwsf:listener name="IBMMQ"
      uri="http://schemas.xmlsoap.org/soap/mq" scheme="ibmmq" default="true"
          class="rwsf_webservice_transport_ibmmq.createIBMMQListener">
    <rwsf:property name="auto-start" value="true"/>
    <rwsf:property name="protocol" value="mq"/>
    <rwsf:property name="serverQueueName"
       value="rwsf.MYSERVICE.QUEUE"/>
    <rwsf:property name="queueManager" value="QM_beaver"/>
    <rwsf:property name="channelDef"
       value="SYSTEM.DEF.SVRCONN/TCP/localhost"/>
  </rwsf:listener>
  -->

Uncomment the code, and use the same settings as on the client. Make sure to use a listener object on the service side, rather than a transport. Also, each service should have its own message queue.

Be sure to set up individual queues on your MQ server so that each HydraExpress service is listening on its own queue.

When you deploy the service, the server-transports.xml is copied to a new directory at <installdir>\apps\servlets\servicename.

When the HydraExpress Agent starts, it will load all the IBM MQ listeners defined in all the server-transports.xml files it finds under apps\servlets.

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.