3 Design-Time and Run-Time Concepts

D3L Disambiguation Order

The disambiguation methods are tried in the following order:

1. If only one D3L is specified in the ota.d3ls parameter, then 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

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 WebSphere MQ 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 WebSphere MQ application can inform the WebSphere MQ 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 that 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 accept 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 Integration InterConnect event and business object names.

Using a D3L Header and Value Pair

The WebSphere MQ adapter supports D3L disambiguation using the header and value attributes. For the WebSphere MQ adapter, transport message headers correspond to the WebSphere MQ message properties. Consequently, transport message header values are identical to WebSphere MQ message property values.

Using the mq.default.event.use_mq_fmt Parameter

This mode enables the WebSphere MQ 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

For example:

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

This requires the following adapter.ini file 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 Integration InterConnect event names, then you can define a the mqfmt2event.ini mapping file in the same directory where adapter.ini file is located. If this file is present, then the adapter will read the file and apply the specified event name mappings 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 

Using the mq.default.event.exit Parameter

This event name resolution method enables 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 the event name corresponding to the message. 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 enables 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, then 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, then the event is resolved as Product.getPrice and the shown D3L file is subsequently used to transform the native byte message into an OracleAS Integration InterConnect Message Object.

If the magic value does not reside at the very beginning of the message, then its 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 preceding methods fail, then the WebSphere MQ 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, then 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.

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;

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 Integration InterConnect receives a reply from the WebSphere MQ 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;