3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the MQ Series adapter.

• MQ Series Adapter Design Time Concepts

• MQ Series Adapter Runtime Concepts

MQ Series Adapter Design Time Concepts

The MQ Series adapter can handle XML and D3L structured payload, for example:

• Pure XML data--String beginning with <?xml....

• Fixed lay-out--Typically binary data described by a D3L XML file.

XML Payload

A DTD can be imported using iStudio that governs how the MQ Series adapter parses a received XML document into an OracleAS InterConnect Application View event and back again, and how an inbound Application View message is converted into an XML document. Use the XML message type when defining a new integration point in the event wizards.

The ota.type parameter in the adapter.ini file must be set to XML and not D3L.

When the MQ Series adapter operates in the XML payload mode, no transformations between the native view and the application view are performed on the messages that are sent or received through the MQ Series adapter, apart from the implied straight ASCII <-> Java object conversion or parsing. Any XSLT transformations take place before sending an XML document to OracleAS InterConnect, or after receiving one from OracleAS InterConnect.

D3L Payload

In addition to pure XML documents, the MQ Series adapter also handles messages that conform to D3L data type definitions, which describe data translations between application view messages and native format.

An application based on the MQ Series adapter can use the use the D3L message type and import D3L data types. When these are selected in the correct wizard, messages received or sent by the MQ Series adapter must adhere to the fixed byte level lay-out defined in an D3L XML file.

Importing D3L data types can also be used to define common view data types.

See Also: Appendix B, Oracle Application Server InterConnect User's Guide

MQ Series Adapter Runtime Concepts

This section describes the runtime concepts for the MQ Series adapter.

How the MQ Series Adapter Works

The MQ Series adapter is comprised of the MQ Series bridge and the agent. The following topics describe how the MQ Series adapter works.

Outbound

Outbound messages are processed using the following steps:

1. The bridge is periodically polling the configured MQ Series outbound queue chosen for receiving messages, as defined by the mq.default.polling_interval parameter. A new message in this queue indicates a new outbound message from MQ Series waiting to be received by the MQ Series adapter.

2. The adapter then picks up the message, converts it from XML or transforms it via the D3L processor, depending on the value of the ota.type parameter, builds the corresponding OracleAS InterConnect application view message, and hands it off the OracleAS InterConnect agent.

3. The OracleAS InterConnect agent then converts the application view event into a common view event and hands it off to the OracleAS InterConnect runtime for further routing and processing.

   Figure 3-1 Outbound Message Routing

   

   Text description of the illustration picture3.gif

The relevant parameters in adapter.ini pertaining to the outbound MQ Series endpoint are mq.default.receiver.* and mq.default.event.*.

See Also: Chapter 2, "Installation and Configuration"

D3L Disambiguation

If the ota.type parameter is set to D3L, the MQ Series bridge uses the D3L processor to parse from native or byte format to an OracleAS InterConnect message object, which then is handed over to the agent as an application view event.

When the MQ Series adapter receives a message from the outbound MQ Series queue while operating in D3L mode, the message is construed as an opaque sequence of bytes. The challenge then becomes how to determine to which OracleAS InterConnect event, and ultimately to which D3L file this message corresponds.

The MQ Series adapter provides six methods to determine this through a combination of header values found in the configured D3L files and the value of one of the mq.default.event.* parameters in the adapter.ini file. These methods are described below.

Note: The term event name as used in this section implies a specification of the OracleAS InterConnect business object as part of the event name, prefixed followed by a dot, for example, Order.getStatus. The event name also synonymously includes OracleAS InterConnect procedure names.

Using the mq.default.event.name Parameter

Using this parameter is the most primitive mode of operation. Using a hard coded event name for all outbound messages received from MQ Series is one example.

• Example: mq.default.event.name=Employee.updateInfo

  This example requires that exactly one D3L file has the following header:

      <?xml version="1.0" encoding="US-ASCII"?> 
      <!DOCTYPE message SYSTEM "d3l.dtd"> 
      <message name="updateInfo" object="Employee" type="... 
      ... 
  

Using the mq.default.event.property Parameter

Use this method if the sending MQ Series application is able to inform the MQ Series adapter about which event a message corresponds to by setting a specified message property to a given value.

To use this method, complete the following:

1. Set the mq.default.event.property parameter to the name of the message property which will contain the native event name.

2. Define one D3L XML for each possible value of this message property, binding the D3L file to a given value of the message property through the use of the D3L header attributes name and object.

• Example: mq.default.event.property=SAP_EvNm

  This property will only assume the two distinct values Order.evtPut and Order.evtGet. Considering this, the following two D3L files should be defined:

  • sap_put.xml

            <?xml version="1.0" encoding="US-ASCII"?> 
            <!DOCTYPE message SYSTEM "d3l.dtd"> 
            <message name="evtPut" object="Order" type="...">
            ...
           
    

  • sap_get.xml

            <?xml version="1.0" encoding="US-ASCII"?> 
            <!DOCTYPE message SYSTEM "d3l.dtd"> 
            <message name="evtGet" object="Order" type="...">
            ...
           
    

Set the ota.d3ls parameter to sap_put.xml,sap_get.xml.

The name and object headers should correspond to the associated OracleAS InterConnect event and business object names.

Using a D3L Header and Value Pair

The MQ Series adapter also supports D3L disambiguation using the header and value attributes. For the MQ Series adapter, transport message headers corresponds to the MQ Series message properties. Consequently, transport message header values means the MQ Series message property values.

See Also: Oracle Application Server InterConnect User's Guide, Appendix B

Using the mq.default.event.use_mq_fmt Parameter

This mode allows the MQ Series message format property to be used to select the corresponding event name. This property is often referred to as the following:

• The MQMD Format field, MQFMT

• In Java, com.ibm.mq.jms.JMSC.FORMAT_PROPERTY

• Example

  Assume the MQFMT field of a received message from MQ Series has the value Cus.new.

  This requires the following adapter.ini setting:

  • mq.default.event.use_mq_fmt=Y

  and the following D3L file:

          <?xml version="1.0" encoding="US-ASCII"?> 
          <!DOCTYPE message SYSTEM "d3l.dtd"> 
          <message name="new" object="Cus" type="..." 
          ...
         
  

Optionally, if the values in the MQFMT field do not easily map into the OracleAS InterConnect event names, the user can define a the mqfmt2event.ini mapping file in the same directory where adapter.ini is located. If present, it will be read and the specified event name mappings applied when a message is received. The format of the file is as follows:

<MQMFMT-field-value-1>=<OAI-business-object-name1>.<OAI-event-name1> 
<MQMFMT-field-value-2>=<OAI-business-object-name2>.<OAI-event-name2> 
... 
<MQMFMT-field-value-n>=<OAI-business-object-namen>.<OAI-event-namen>

• Example

      CustNew=Customer.createCustomer 
      CustUpd=Customer.updateCustomer 
  

  Note: More than one MQMFT field value can map to the same event name.

  Note: The business object and event names on the right hand side of the equal sign in the mqfmt2event.ini file must be matched by corresponding name and object attribute values in the associated D3L files.

Using the mq.default.event.exit Parameter

This event name resolution method allows a Java class call-out to be registered which is given a reference to the received JMS message. In return, the Java class call-out must tell the bridge which event name to which the message corresponds. The Java class must implement the oracle.oai.agent.adapter.mqseries.MQEventExit interface, which has the following signature:

public interface MQEventExit
{
    public String getEventName(javax.jms.Message jmsMessage)
        throws oracle.oai.agent.adapter.mqseries.MQBridgeException;

• Example: myEventExit.java

      import oracle.oai.agent.adapter.mqseries.MQBridgeException;
      public class myEventExit
          implements oracle.oai.agent.adapter.mqseries.MQEventExit
      {
          public String getEventName(Message jmsMessage)
             throws MQBridgeException
          {
              try
              {
                  if (jmsMessage instanceof TextMessage)
                  {
                      String body  = ((TextMessage)jmsMessage).getText();
                      String bizObj = body.substring(1,10);
                      String event  = body.substring(21,30);
                      return bizObj + "." + event;
                  }
                   else
                      throw new MQBridgeException("Wrong message type");
              }
              catch (Exception e) {
                  throw new MQBridgeException("Error", e);
              }
          }
      }
  

Using D3L Magic

The D3L syntax allows a magic header attribute to be specified. If specified, the header corresponds to a sequence of bytes, specified in UTF-8 bytes, hexadecimal, or octal, that should occur at the very beginning of the native-format message. If the magic attribute in one of the registered D3L files (defined in the ota.d3ls parameter) matches the bytes at the beginning of the native message, that D3L header name and object attributes are chosen as the event name.

• Example: prod_getprice.xml

      <?xml version="1.0" encoding="US-ASCII"?> 
      <!DOCTYPE message SYSTEM "d3l.dtd">
      <message name="getPrice" object="Product" type="..."
          magic="SYSPR01GETPRC"
      ...
      
  

If the byte stream of a received message begins with the characters SYSPR01GETPRC, the event is resolved as Product.getPrice and the shown D3L file is subsequently used to transform the native byte message into an OracleAS InterConnect Message Object.

If the magic value does not reside at the very beginning of the message, it's starting position can be offset by using the D3L message element attribute startsat.

For example:

<message name = "getPrice" magic="SYSPR01GETPRC" startsat="18" ...>

Trying All D3Ls Until One Works

If any of the above methods fail, the MQ Series adapter falls back to a trial-and-error resolution scheme where each registered D3L file is tried until one succeeds. This means applying all files in the order they are listed in the ota.d3ls parameter in the adapter.ini file. If none of the D3L files succeed, the entire D3L disambiguation process for a given message will terminates and an error message is logged. The failed message is saved in the directory where the adapter.ini file is located, under a name such as MQ.FailedMsg.<message-id>.

D3L Disambiguation Order

The above disambiguation methods are tried in the following order:

1. If only one D3L is specified in the ota.d3ls parameter, it is always used.

2. Using a D3L Header and Value Pair

3. Using D3L Magic

4. Using the mq.default.event.name Parameter

5. Using the mq.default.event.use_mq_fmt Parameter

6. Using the mq.default.event.property Parameter

7. Using the mq.default.event.exit Parameter

8. Trying All D3Ls Until One Works

Inbound

The MQ Series adapter only supports sending to a single MQ Series inbound endpoint, as shown in Figure 3-2. A future edition of the MQ Series adapter will support multiple inbound endpoints.

Figure 3-2 Inbound Message Routing

Text description of the illustration picture4.gif

The mq.default.sender.* parameter in the adapter.ini file pertains to the default inbound MQ Series endpoint.

Support for Request-Reply in D3L Mode

The MQ Series adapter supports the OracleAS InterConnect PUBLISH, REQUEST, and REPLY message types. Expressed in iStudio terms, the MQ Series adapter can publish or subscribe any event and invoke or implement any procedure.

Note: The HTTP, FTP, and SMTP adapters only support publish and subscribe.

The support for invoke and implement messages, such as Procedure calls, is enabled by the native support for request and reply messages in MQ Series, including its message correlation capability. It is only available when the MQ Series adapter operates in D3L mode.

In order to take advantage of this capability, a few extra steps need to be performed during configuration, including modifying the D3L files and defining correlation fields in iStudio.

The following instructions are based on a small example:

• Business Object--Product

• Procedure--getPrice

• Input parameters--ProductID and CustomerID as integers.

• Output parameters--ProductID as an integer and Price and Discount as floats.

These data types must be defined in two separate D3L files, one defining the native input (request) data structure, and one defining the native output (reply) data structure. The following two D3L files could serve this purpose.

getPriceIn.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd">
<message type="getPriceInput" name="getPrice" object="Product">

    <!-- ID type -->
    <unsigned4 id="ID" endian="little" />
    
    <struct id="getPriceInput">
    
        <field name="ProductID">     <typeref type="ID" />
    </field>
        <field name="CustomerID">    <typeref type="ID" />
    </field>
    </struct>
    
</message>

getPriceOut.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd"> 

<message type="getPriceOutput" name="getPrice" object="Product" reply="Y"> 

    <!-- ID type -->
    <unsigned4 id="ID" endian="little" />

    <!-- Float, as decimal number format enclosed by '$' -->
    <number id="Float"><limstring delimiter="$" /></number>

    <struct id="getPriceOutput"> 
        <field name="ProductID">   <typeref type="ID" />     </field> 
        <field name="Price">       <typeref type="Float" />  </field> 
        <field name="Discount">    <typeref type="Float" />  </field> 
    </struct>

</message>

It is assumed that the 'partner' application will be based on the Database adapter.

The next paragraphs describe the two possible scenarios, and how to correctly setup OracleAS InterConnect to handle them:

• The MQ Series adapter in the role as the invoker.

• The MQ Series adapter in the role as the implementor.

Invoking the Product.getPrice Procedure Using the MQ Series Adapter

To invoke a procedure using the MQ Series adapter in iStudio:

1. Right-click on Invoked Procedures for the MQ Series application and select New.

   The Invoke Wizard--Select a Procedure page displays.

2. Select getPrice as the Application.

3. Set the Message Type to D3L.

4. Click Next.

   The Define Application View page displays.

5. Click Import and select D3L.

6. Select the getPriceIn.xml file and mark as it as IN.

7. Select the getPriceOut.xml file and mark as it as OUT.

8. Click OK, then click Finish.

9. Go to the following directory and copy the two XML files (get*.xml) to this directory.

   Platform	Action
   Windows	ORACLE_HOME\oai\9.0.4\adapters\<mqapp>
   UNIX	ORACLE_HOME/oai/9.0.4/adapters/<mqapp>

10. List the two XML file names in the ota.d3ls parameter in the adapter.ini file, for example:

        ota.d3ls=getPriceIn.xml,getPriceOut.xml
        
    

11. Mark the getPriceOut.xml D3L file as the REPLY. The MQ Series adapter does not allow two D3L files defining the same BusinessObject and EventName. Use the D3L message element attribute reply as follows:

        <message type="getPriceOutput" name="getPrice" object="Product" reply="Y">
    
    
    
    

12. Decide and configure the D3L disambiguation scheme which enables the MQ Series adapter, to correctly select the getPriceIn.xml D3L file when it reads an outbound message from MQ Series, using header/value disambiguation. For example:

        <message type="getPriceInput" name="getPrice" object=
        "Product" header="D3Lselector" value="getprice">
        
    

In (native) Invoking Application (JMS example)

 // This 3rd party application will send a REQUEST message to 
// OAI (Invoke role), and then await a REPLY. 
    BytesMessage reqMessage = session.createBytesMessage(); 
    byte[] getPriceMsg = new byte[] { 20, 0, 0, 0, 10, 0, 0, 0 };
    reqMessage.writeBytes(nativeBytes, 0, nativeBytes.length); 
    reqMessage.setJMSReplyTo((Destination)replyQueue);
    reqMessage.setStringProperty("D3Lselector", "getprice");
    reqMessage.setIntProperty("JMS_IBM_MsgType", (int)1); //
REQUEST
    // Send REQUEST
    queueSender.send(reqMessage);
    session.commit(); 
    ...
    // Await REPLY
    Message replyMessage = queueReceiver.receive();
    if (replyMessage instanceof BytesMessage) 
    {
        if (replyMessage.getJMSCorrelationID().
            equals(reqMessage.getJMSMessageID()))
            // Got my reply back!

In (PL/SQL) Implementing Application

PROCEDURE getprice(productID  IN OUT INTEGER,
                   customerID IN     INTEGER,
                   price         OUT NUMBER,
                   discount      OUT NUMBER)
IS
BEGIN
  -- Just return something
  price := 1499.95;
  discount := 10.0;
END;

Which gets invoked from the stub generated by iStudio:

PACKAGE BODY Product AS
    PROCEDURE imp_getPrice_QA_V1(io_PRODUCTID IN OUT NUMBER, 
                                 i_CUSTOMERID IN     NUMBER, 
                                 o_PRICE         OUT NUMBER, 
                                 o_DISCOUNT      OUT NUMBER) 
AS 
BEGIN
    getprice(io_PRODUCTID, i_CUSTOMERID, o_PRICE, o_DISCOUNT);
END imp_getPrice_QA_V1;

Implementing Product.getPrice Procedure Using the MQ Series Adapter

To implement a procedure using the MQ Series adapter in iStudio:

1. Right-click on Implemented Procedures for the MQ Series application and select New.

   The Implement Wizard--Select a Procedure page displays.

2. Select getPrice as the Application.

3. Set the Message Type to D3L and click Next.

   The Define Application View page displays.

4. Click Import and select D3L.

5. Select the getPriceIn.xml file and mark as it as IN.

6. Select the getPriceOut.xml file and mark as it as OUT.

7. Click OK.

   The Define Correlation Fields page displays.

8. Select the two fields in the Input and Output data structures. These fields are used to correlate a response to its original request.

9. Click OK, then click Finish.

10. Go to the following directory and copy the two XML files (get*.xml) to this directory.

    Platform	Action
    Windows	ORACLE_HOME\oai\9.0.4\adapters\<mqapp>
    UNIX	ORACLE_HOME/oai/9.0.4/adapters/<mqapp>

11. List the two XML file names in the ota.d3ls parameter in the adapter.ini file, for example:

        ota.d3ls=getPriceIn.xml,getPriceOut.xml
    
    
    
    

12. Mark the getPriceOut.xml D3L file as the REPLY. The MQ Series adapter does not allow two D3Ls defining the same BusinessObject and EventName. Use the D3L message element attribute reply, as follows:

        <message type="getPriceOutput" name="getPrice" object="Product" reply="Y"> 
    
    
    
    

13. Decide and configure the D3L disambiguation scheme which enables the MQ Series adapter, to correctly select the getPriceOut.xml D3L file when it reads an outbound message from MQ Series. The following example uses header/value disambiguation:

        <message type="getPriceOutput" name="getPrice" object="Product" reply="Y" 
        header="D3Lselector" value="getpricereply">
    

In (Native) Implementing (or Invoked) Application (JMS Example)

// This 3rd party application will consume/read a REQUEST message from 
// OAI (Implement role), and return a REPLY.

// Read REQUEST
Message reqMessage = queueReceiver.receive(); 

if (reqMessage instanceof BytesMessage)
{
    // Extract ProductID from request
    byte[] productID = new byte[4];
    ((BytesMessage)reqMessage).readBytes(productID); 
    
    // Construct reply (binary lay-out message)
    byte[] getPriceReply = new byte[] {
        0, 0, 0, 0,                        // Product ID
        '$', '2','0','0','.','7','5','$',  // Price 
        '$',     '1','5','.','1','0','$'   // Discount 
    };
    
    // Copy the Product ID received in Request into the Reply 
    // so OAI can correlate the reply to the original request.
    for (int i = 0; i < 4; i++)
        getPriceReply[i] = productID[i];
    ....

    BytesMessage replyMessage = session.createBytesMessage();
    replyMessage.writeBytes(getPriceReply, 0, getPriceReply.length);

        replyMessage.setJMSCorrelationID(reqMessage.getJMSMessageID()); 
        replyMessage.setIntProperty("JMS_IBM_MsgType", (int)2); // REPLY 
        replyMessage.setStringProperty("D3Lselector", "getpricereply"); 

    // Send REPLY
    queueSender.send(replyMessage);
    session.commit();

In (PL/SQL) Invoking Application (Asynchronously)

-- Invoking procedure 
PROCEDURE INVGETPRICE(prodID IN NUMBER, custID IN NUMBER)
AS
    moid  NUMBER;
    aoid  NUMBER;
    naoid NUMBER;
BEGIN
    Product.crMsg_getPrice_QA_V1(moid, aoid);
    naoid := Product.cr_getPriceInput_getPriceInput(prodID, custID, moid, aoid);
    Product.inv_getPrice_QA_V1(moid, 'DBAPP');
END;

When OracleAS InterConnect receives back a reply back from the MQ Series application, it invokes a procedure, for example:

PROCEDURE sub_getPrice_QA_V1(getPriceOutput IN dbapp_getPriceOutput_QA_V1)
AS
BEGIN
    -- Save Reply
    INSERT INTO price_reply (prodid, price, discount)
    VALUES (getPriceOutput.ProductID,
        getPriceOutput.Price,
        getPriceOutput.Discount);
END sub_getPrice_QA_V1;