|
Oracle® Application Server Integration InterConnect Adapter for WebSphere MQ Installation and User's Guide
10g Release 2 (10.1.2) B14072-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Integration InterConnect Adapter for WebSphere MQ Installation and User's Guide
10g Release 2 (10.1.2) B14072-02 |
|
|
Previous |
Next |
This chapter describes the design-time and run-time concepts for the WebSphere MQ adapter. It contains the following topics:
The WebSphere MQ adapter can handle XML and D3L structured payloads, such as pure XML data with strings beginning with <xml..., and binary data described by a D3L XML file.
You can import a Document Type Definition (DTD) or XML Schema Definition (XSD) in iStudio, which determines how the WebSphere MQ adapter parses a received XML document into an OracleAS Integration InterConnect application view event. In addition, you can use the XSD or DTD to describe how an inbound application view message is converted to an XML document. Use the message type option XML when defining a new integration point in any of the event wizards.
Ensure that the ota.type parameter in the adapter.ini file is set to XML, instead of D3L.
When the WebSphere MQ adapter operates in the XML payload mode, no transformations are performed on the messages between native view and application view. Any Extensible Stylesheet Language Transformations (XSLT) should be performed either before sending an XML document to OracleAS Integration InterConnect, or after receiving one from OracleAS Integration InterConnect.
The WebSphere MQ adapter performs a two-way conversion and transformation of messages between application view and native format.
An application based on the WebSphere MQ adapter can use the iStudio Message Type D3L and the iStudio D3L Data Type Import options when importing a data type. In this case, messages received or sent by the WebSphere MQ adapter must adhere to the fixed byte-level layout defined in a D3L XML file.
The D3L Data Type Import option can also define common view datatypes.
|
See Also: Oracle Application Server Integration InterConnect User's Guide, Appendix B, for additional information on D3L |
This section describes the key run-time components of the WebSphere MQ adapter. It contains the following topics:
This section gives an overview of how the WebSphere MQ adapter works. It contains the following topics:
The WebSphere MQ adapter is comprised of the bridge and the run-time agent. The bridge constantly polls the queue chosen for publishing messages in the WebSphere MQ outbound queue. A new message in this queue indicates a new outbound OracleAS Integration InterConnect message waiting to be sent by the adapter. The adapter picks up the message, builds the corresponding OracleAS Integration InterConnect message, persists it, transforms it to the common view, and routes it to the hub. From the hub, the message is routed to the suitable subscriber.
The relevant parameters in adapter.ini pertaining to the outbound WebSphere MQ endpoint are mq.default.receiver.* and mq.default.event.*.
If the ota.type parameter is set to D3L, then the WebSphere MQ bridge uses the D3L processor to parse from native or byte format to an OracleAS Integration InterConnect message object, which then is handed over to the agent as an application view event.
When the WebSphere MQ adapter receives a message from the outbound WebSphere MQ queue while operating in D3L mode, the message is construed as an sequence of bytes. The processe of determining the OracleAS Integration InterConnect event and the D3L to which this message corresponds is called D3L Disambiguation.
The WebSphere MQ adapter has 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 as follows.
|
Note: The term event name as used in this section implies a specification of the OracleAS Integration 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 Integration InterConnect procedure names.
|
The disambiguation methods are tried in the following order:
If only one D3L is specified in the ota.d3ls parameter, then it is always used.
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="... ...
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:
Set the mq.default.event.property parameter to the name of the message property that will contain the native event name.
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.
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.
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
|
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 themqfmt2event.ini file must be matched by corresponding name and object attribute values in the associated D3L files.
|
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);
}
}
}
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" ...>
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.
|
Note: The adapter subscribing to an event should be started before any other adapter can publish that event. If you publish an event before starting the subscribing adapter, then the event would not be delivered to the subscribing adapter. |
The WebSphere MQ adapter only supports sending to a single WebSphere MQ inbound endpoint, as shown in Figure 3-2.
The mq.default.sender.* parameter in the adapter.ini file pertains to the default inbound WebSphere MQ endpoint.
The WebSphere MQ adapter can publish or subscribe any event and invoke or implement any procedure.
The support for invoke and implement messages, such as Procedure calls, is enabled by the native support for request and reply messages in WebSphere MQ, including its message correlation capability. It is only available when the WebSphere MQ adapter operates in D3L mode.
For request/reply scenario, some additional steps must 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.
<?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>
<?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.
To invoke a procedure using the WebSphere MQ adapter in iStudio:
Right-click Invoked Procedures for the WebSphere MQ application and select New. The Invoke Wizard - Select a Procedure page is displayed.
Select getPrice as the Application.
Set the Message Type to D3L.
Click Next. The Define Application View page is displayed.
Click Import and select D3L.
Select the getPriceIn.xml file and mark as it as IN.
Select the getPriceOut.xml file and mark as it as OUT.
Click OK, and then click Finish.
Change to the following directory and copy the two XML files (get*.xml) to this directory.
| Platform | Action |
|---|---|
| UNIX | ORACLE_HOME/integration/interconnect/adapters/<mqapp>
|
| Windows | ORACLE_HOME\integration\interconnect\adapters\<mqapp>
|
List the two XML file names in the ota.d3ls parameter in the adapter.ini file, for example:
ota.d3ls=getPriceIn.xml,getPriceOut.xml
Mark the getPriceOut.xml D3L file as the REPLY. The WebSphere MQ adapter does not allow two D3L files defining the same business object and event name. Use the D3L message element attribute reply as follows:
<message type="getPriceOutput" name="getPrice" object="Product" reply="Y">
Decide and configure the D3L disambiguation scheme that enables the WebSphere MQ adapter to correctly select the getPriceIn.xml D3L file when it reads an outbound message from WebSphere MQ, using header/value disambiguation. For example:
<message type="getPriceInput" name="getPrice" object= "Product" header="D3Lselector" value="getprice">
// 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!
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;
To implement a procedure using the WebSphere MQ adapter in iStudio:
Right-click Implemented Procedures for the WebSphere MQ application and select New. The Implement Wizard - Select a Procedure page is displayed.
Select getPrice as the Application.
Set the Message Type to D3L and click Next. The Define Application View page is displayed.
Click Import and select D3L.
Select the getPriceIn.xml file and mark it as IN.
Select the getPriceOut.xml file and mark it as OUT.
Click OK. The Define Correlation Fields page is displayed.
Select the two fields in the Input and Output data structures. These fields are used to correlate a response to its original request.
Click OK and then click Finish.
Change to the following directory and copy the two XML files (get*.xml) to this directory.
| Platform | Action |
|---|---|
| UNIX | ORACLE_HOME/integration/interconnect/adapters/<mqapp>
|
| Windows | ORACLE_HOME\integration\interconnect\adapters\<mqapp>
|
List the two XML file names in the ota.d3ls parameter in the adapter.ini file, for example:
ota.d3ls=getPriceIn.xml,getPriceOut.xml
Mark the getPriceOut.xml D3L file as the REPLY. The WebSphere MQ 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">
Decide and configure the D3L disambiguation scheme that enables the WebSphere MQ adapter to correctly select the getPriceOut.xml D3L file when it reads an outbound message from WebSphere MQ. The following example uses header/value disambiguation:
<message type="getPriceOutput" name="getPrice" object="Product" reply="Y" header="D3Lselector" value="getpricereply">
// 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();
-- 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;
The process for starting the adapter varies based on the operating system.
To start the WebSphere MQ adapter on Unix:
Change to the directory containing the start script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type start and press Enter.
To start the WebSphere MQ adapter from Services on Windows:
Access the Services window from the Start menu.
The Services window is displayed.
Select the OracleHomeOracleASIntegrationInterConnectAdapter-Application service.
Start the service based on the operating system.
The WebSphere MQ adapter automatically starts the publishing engine, a tool for notifying foreign applications of additions, deletions, or updations to the native application.
|
Note: You can also start and stop the WebSphere MQ adapter using the IC Manager. Refer to Oracle Application Server Integration InterConnect User's Guide for more details. |
You can verify the start up status of the WebSphere MQ adapter by viewing the log.xml files. The files are located in the time-stamped subdirectory of the log directory of the WebSphere MQ adapter. Subdirectory names have the following form:
timestamp_in_milliseconds
The following is an example of the information about an WebSphere MQ adapter that started successfully:
The Adapter service is starting.. Registering your application (MQAPP).. Initializing the Bridge oracle.oai.agent.adapter.mqseries.MQBridge.. Starting the Bridge oracle.oai.agent.adapter.mqseries.MQBridge.. Service started successfully.
The process for stopping the adapter varies based on the operating system.
To stop the WebSphere MQ adapter on UNIX:
Change to the directory containing the stop script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type stop and press Enter.
To stop the WebSphere MQ adapter from Services on Windows.
Access the Services window from the Start menu.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Stop the service based on the operating system.
You can verify the stop status of the WebSphere MQ adapter by viewing the log.xml files. These files are located in the time-stamped subdirectory of the log directory of the WebSphere MQ adapter.
