Using IBM WebSphere MQ Adapters with Ensemble
Using the IBM WebSphere MQ Inbound Adapter
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes the default behavior of the Ensemble IBM WebSphere MQ inbound adapter (EnsLib.MQSeries.InboundAdapter) and describes how to use this adapter in your productions. It discusses the following topics:

Overall Behavior
First, it is useful to understand the details that you specify for the adapter. The EnsLib.MQSeries.InboundAdapter class provides runtime settings that you use to specify items like the following:
In general, the inbound IBM WebSphere MQ adapter (EnsLib.MQSeries.InboundAdapter) periodically checks the given queue, retrieves any messages, and sends the messages (as instances of EnsLib.MQSeries.Message) to the associated business service. The business service, which you create and configure, uses these messages and communicates with the rest of the production. The following figure shows the overall flow:
More specifically:
  1. When the adapter is initialized, it connects to the given queue manager and queue, using the given channel.
  2. The adapter regularly executes its OnTask() method, which retrieves a message from the queue (if a message is available). The polling interval is determined by the CallInterval setting.
  3. When the adapter retrieves a message, it does the following:
    1. The adapter creates an instance of the EnsLib.MQSeries.Message class and puts the message data into it.
    2. The adapter calls the internal ProcessInput method of the associated business service class, passing the EnsLib.MQSeries.Message instance as input.
    Note:
    The message must be less than 32 KB in length unless long strings are enabled in Ensemble.
  4. The internal ProcessInput() method of the business service class executes. This method performs basic Ensemble tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.
  5. The ProcessInput() method then calls your custom OnProcessInput() method, passing the EnsLib.MQSeries.Message instance as input. The requirements for this method are described later in Implementing the OnProcessInput Method.”
The response message follows the same path, in reverse.
Creating a Business Service to Use the Inbound Adapter
To use this adapter in your production, create a new business service class as described here. Later, add it to your production and configure it. You must also create appropriate message classes, if none yet exist. See Defining Ensemble Messages in Developing Ensemble Productions.
The following list describes the basic requirements of the business service class:
The following example shows the general structure that you need:
Class EMQS.Service Extends Ens.BusinessService 
{
Parameter ADAPTER = "EnsLib.MQSeries.InboundAdapter";

Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
                      pOutput As %RegisteredObject) As %Status
{
   set tsc=$$$OK
   //your code here
   Quit tsc
}
}
Note:
Studio provides a wizard that you can use to create a business service stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Service and click OK. Note that the wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit the method signature to use the specific input argument needed with this adapter; the input argument type should be EnsLib.MQSeries.Message.
Implementing the OnProcessInput() Method
Within your custom business service class, your OnProcessInput() method should have the following signature:
Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
                      pOutput As %RegisteredObject) As %Status
Here pInput is the message object that the adapter will send to this business service; this is an instance of EnsLib.MQSeries.Message. Also, pOutput is the generic output argument required in the method signature.
The OnProcessInput() method should do some or all of the following:
  1. Examine the MQ message (EnsLib.MQSeries.Message) and decide how to use it. See Using the Received Message,” later in this chapter.
  2. Create an instance of the request message, which will be the message that your business service sends.
    For information on creating message classes, see Defining Ensemble Messages in Developing Ensemble Productions.
  3. For the request message, set its properties as appropriate, using values in the MQ message.
  4. Call a suitable method of the business service to send the request to some destination within the production. Specifically, call SendRequestSync(), SendRequestAsync(), or (less common) SendDeferredResponse(). For details, see Sending Request Messages in Developing Ensemble Productions
    Each of these methods returns a status (specifically, an instance of %Status).
  5. Make sure that you set the output argument (pOutput). Typically you set this equal to the response message that you have received. This step is required.
  6. Return an appropriate status. This step is required.
See the example at the end of this chapter.
Using the Received Message
The adapter sends an instance of EnsLib.MQSeries.Message to your business service. This object contains the message retrieved from the queue. It has three properties:
Note:
The message retrieved from the queue must be less than 32 KB in length unless long strings are enabled in Ensemble.
Example
The following business service retrieves messages and forwards them to a business host named EMQS.MessageProcessor.
Class EMQS.Service Extends Ens.BusinessService 
{

Parameter ADAPTER = "EnsLib.MQSeries.InboundAdapter";

Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
pOutput As EMQS.InboundMsg) As %Status
{
    //create Ensemble message to carry the retrieved MQ message
    Set inbound=##class(EMQS.InboundMsg).%New()
    Set inbound.Body=pInput.Body
    Set inbound.MessageId=pInput.MessageId

    //forward this to the message processor
    Set tsc=..SendRequestSync("EMQS.MessageProcessor",inbound,.response)
    Set pOutout=response
    Quit tsc
}

}
The message class EMQS.InboundMsg is as follows:
Class EMQS.InboundMsg Extends Ens.Request
{

Property Body As %String (MAXLEN="");

Property MessageId As %String(MAXLEN = 128);

}
Adding and Configuring the Business Service
To add your business service to an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your business service class to the Ensemble production.
  2. Enable the business service.
  3. Configure the adapter to access an IBM WebSphere MQ queue and retrieve messages. Specifically:
    These topics are discussed in the section “Settings for the IBM WebSphere MQ Adapters.”
  4. Run the production.