Overview of adapter processing

The adapter makes use of IBM's WebSphere MQ implementation of the Java Message Service (JMS). The JMS is an open-standard API for accessing enterprise-messaging systems. It is designed to allow business applications to asynchronously send and receive business data and events.

The adapter does not directly interact with WBI Message Broker. As part of configuring the connector, you set up WebSphere MQ queues as the input and output nodes for the WBI Message Broker message flows. The adapter communicates with a WebSphere MQ queue manager that hosts the message broker to which the message flows are deployed.

Message request

Figure 2 illustrates a message request communication for the connector, the adapter's runtime component. When the doVerbFor() method receives a business object from a collaboration, the connector passes the business object to the data handler. The data handler converts the business object into a suitable message and issues it to a queue. There, the JMS layer makes the appropriate calls to open a queue session and route the message. You can configure the connector to issue requests asynchronously (fire and forget). Or you can configure connector properties to enable synchronous request processing.

Figure 2. Message request processing


The connector processes business objects passed to it by a collaboration based on the verb for each business object. The connector uses business object handlers and the doVerbFor() method to process the business objects that the connector supports. The connector supports the following business object verbs:

Note:
Business objects with Create, Update, and Delete verbs can be issued either asynchronously or synchronously. The default mode is asynchronous. The connector does not support asynchronous delivery for business objects with the Retrieve, Exists, or Retrieve by Content verbs. Accordingly, for Retrieve, Exists, or Retrieve by Content verbs, the default mode is synchronous.

Create, update, and delete

Processing of business objects with create, update and delete verbs depends on whether the objects are issued asynchronously or synchronously.

Asynchronous delivery

This is the default delivery mode for business objects with Create, Update, and Delete verbs. A message is created from the business object using a data handler and then written to the output queue. If the message is delivered, the connector returns SUCCESS, else FAIL.

Note:
The connector has no way of verifying whether the message is received or if action has been taken.

Synchronous delivery

If a ReplyToQueue has been defined in the connector-specific properties and a responseTimeout exists in the meta-object conversion properties for the business object, the connector issues a request in synchronous mode. The connector then waits for a response to verify that appropriate action was taken by the receiving application.

For WebSphere Integration Message Broker, the connector initially issues a message with a header as shown in Table 2.

Table 2.

Request message descriptor header (MQMD)
Field Description Value
Format
Format name Output format as defined in the meta-object conversion properties and truncated to 8 characters to meet IBM requirements (example: MQSTR)
MsgType
Message type MQMT_DATAGRAM*
Report
Options for report message requested. When a response message is expected, this field is populated as follows:MQRO_PAN* to indicate that a positive-action report is required if processing is successful.MQRO_NAN* to indicate that a negative-action report is required if processing fails.MQRO_COPY_MSG_ID_TO_CORREL_ID* to indicate that the correlation ID of the report generated should equal the message ID of the request originally issued.
ReplyToQ Name of reply queue When a response message is expected this field is populated with the value of connector property ReplyToQueue.
Persistence
Message persistence MQPER_PERSISTENT*
Expiry
Message lifetime MQEI_UNLIMITED*

* Indicates constant defined by IBM.

The message header described in Table 2 is followed by the message body. The message body is a business object that has been serialized using the data handler.

The Report field is set to indicate that both positive and negative action reports are expected from the receiving application. The thread that issued the message waits for a response message that indicates whether the receiving application was able to process the request.

When an application receives a synchronous request from the connector, it processes the business object and issues a report message as described in Table 3, Table 4, and Table 5.

Table 3.

Response message descriptor header (MQMD)
Field Description Value
Format Format name Input format of busObj as defined in the conversion properties.
MsgType Message type MQMT_REPORT*

*Indicates constant defined by IBM.

Table 4.

Population of response message
Verb Feedback field Message body
Create, update, or delete

SUCCESS

VALCHANGE

(Optional) A serialized business object reflecting changes.

VALDUPES

FAIL

(Optional) An error message.


Table 5. WebSphere Integration Message Broker feedback codes and WebSphere business integration system response values

WebSphere Integration Message Broker feedback code Equivalent WebSphere business integration system response*
MQFB_PAN or MQFB_APPL_FIRST SUCCESS
MQFB_NAN or MQFB_APPL_FIRST + 1 FAIL
MQFB_APPL_FIRST + 2

VALCHANGE

MQFB_APPL_FIRST + 3

VALDUPES

MQFB_APPL_FIRST + 4

MULTIPLE_HITS

MQFB_APPL_FIRST + 5

FAIL_RETRIEVE_BY_CONTENT

MQFB_APPL_FIRST + 6

BO_DOES_NOT_EXIST

MQFB_APPL_FIRST + 7 UNABLE_TO_LOGIN (results in immediate termination of connector agent)
MQFB_APPL_FIRST + 8 APP_RESPONSE_TIMEOUT

*See the Connector Development Guide for details.

If the business object can be processed, the application creates a report message with the feedback field set to MQFB_PAN (or a specific WebSphere business integration system value). Optionally the application populates the message body with a serialized business object containing any changes. If the business object cannot be processed, the application creates a report message with the feedback field set to MQFB_NAN (or a specific WebSphere business integration system value) and then optionally includes an error message in the message body. In either case, the application sets the correlationID field of the message to the messageID of the connector message and issues it to the queue specified by the ReplyToQueue field.

Upon retrieval of a response message, the connector by default matches the correlationID of the response to the messageID of a request message. The connector then notifies the thread that issued the request. Depending on the feedback field of the response, the connector either expects a business object or an error message in the message body. If a business object was expected but the message body is not populated, the connector simply returns the same business object that was originally issued by InterChange Server for the Request operation. If an error message was expected but the message body is not populated, a generic error message will be returned to InterChange Server along with the response code. However, you can also use a message selector to identify, filter and otherwise control how the adapter identifies the response message for a given request. This message selector capability is a JMS feature. It applies to synchronous request processing only and is described below.

Retrieve, exists and retrieve by content

Business objects with the Retrieve, Exists, and Retrieve By Content verbs support synchronous delivery only. The connector processes business objects with these verbs as it does for the synchronous delivery defined for create, update and delete. However, when using Retrieve, Exists, and Retrieve By Content verbs, the responseTimeout and replyToQueue are required. Furthermore, for Retrieve By Content and Retrieve verbs, the message body must be populated with a serialized business object to complete the transaction.

Table 6 shows the response messages for these verbs.

Table 6. Population of response message

Verb Feedback field Message body
Retrieve or RetrieveByContent

FAIL FAIL_RETRIEVE_BY_CONTENT

(Optional) An error message.

MULTIPLE_HITS SUCCESS

A serialized business object.
Exist

FAIL

(Optional) An error message.

SUCCESS


Event processing

Figure 3 illustrates connector event processing. The pollForEvents() method retrieves the next applicable message from the input queue. The message is staged in the in-progress queue where it remains until processing is complete. Using the connector meta-object, the connector first determines whether the message type is supported. If so, the connector passes the message to the configured data handler, which converts the message into a business object. The verb that is set reflects the conversion properties established for the message type. The connector then determines whether the business object is subscribed to by a collaboration. If so, the gotApplEvents() method delivers the business object to the integration broker, and the message is removed from the in-progress queue.

For event notification, the connector detects events written to a queue by an application rather than a database trigger. An event occurs when an application or other MQ-capable software generates WebSphere MQ messages and stores them on the MQ message queue.

Figure 3. Application-connector communication method: Message return


Retrieval

The connector uses the pollForEvents() method to poll the MQ queue at regular intervals for messages. When the connector finds a message, it retrieves it from the MQ queue and examines it to determine its format. If the format has been defined in the connector meta-object, the connector uses the data handler to generate an appropriate business object with a verb. See "Overview of error handling" for event failure scenarios.

The connector processes messages by first opening a transactional session to the input queue. This transactional approach allows for a small chance that a business object could be delivered to a collaboration twice due to the connector successfully submitting the business object but failing to commit the transaction in the queue. To avoid this problem, the connector moves all messages to an i n-progress queue. There, the message is held until processing is complete. If the connector shuts down unexpectedly during processing, the message remains in the in-progress queue instead of being reinstated to the original input queue.

Note:
Transactional sessions with a JMS service provider require that every requested action on a queue be performed and committed before events are removed from the queue. Accordingly, when the connector retrieves a message from the queue, it does not commit to the retrieval until three things occur: 1) The message has been converted to a business object; 2) the business object is delivered to InterChange Server by the gotApplEvents() method, and 3) a return value is received.

Recovery

Upon initialization, the connector checks the in-progress queue for messages that have not been completely processed, presumably due to a connector shutdown. The connector configuration property InDoubtEvents allows you to specify one of four options for handling recovery of such messages: fail on startup, reprocess, ignore, or log error.

Fail on startup

With the fail on startup option, if the connector finds messages in the in-progress queue during initialization, it logs an error and immediately shuts down. It is the responsibility of the user or system administrator to examine the message and take appropriate action, either to delete these messages entirely or move them to a different queue.

Reprocess

With the reprocessing option, if the connector finds any messages in the in-progress queue during initialization, it processes these messages first during subsequent polls. When all messages in the in-progress queue have been processed, the connector begins processing messages from the input queue.

Ignore

With the ignore option, if the connector finds any messages in the in-progress queue during initialization, the connector ignores them, but does not shut down.

Log error

With the log error option, if the connector finds any messages in the in-progress queue during initialization, it logs an error but does not shut down.

Archiving

If the connector property ArchiveQueue is specified and identifies a valid queue, the connector places copies of all successfully processed messages in the archive queue. If ArchiveQueue is undefined, messages are discarded after processing. For more information on archiving unsubscribed or erroneous messages, see "Overview of error handling".

Note:
By JMS conventions, a retrieved message cannot be issued immediately to another queue. To enable archiving and re-delivery of messages, the connector first produces a second message that duplicates the body and the header (as applicable) of the original. To avoid conflicts with the JMS service provider, only JMS-required fields are duplicated. Accordingly, the format field is the only additional message property that is copied for messages that are archived or re-delivered.

Copyright IBM Corp. 1997, 2004