Overview for creating new receivers

Receivers are transport-specific. WebSphere Partner Gateway ships with receivers for FTP directory, JMS, File directory, SMTP (POP3), FTP/S Scripting, and HTTP/S transports. To add a new transport to the WebSphere Partner Gateway system, you can write your own receivers, using an API provided with WebSphere Partner Gateway. Use the Community Console to configure your new receivers, and then integrate them into the processing flow in the normal way. This section describes the process of developing a new receiver. It covers the following topics:

Receiver flow

The nature of the processing flow inside a receiver is in part dictated by the needs of the particular transport, but there are basic tasks that all receivers must accomplish. This section describes those tasks in a high level, general way.

1. Detect message arrival on transport
Receivers use one of two methods to detect request message arrival: polling the targets defined for this transport, as the provided JMS receiver does, or receiving callbacks from the transport, as the provided HTTP/S receiver does.
2. Retrieve message from transport
The receiver retrieves the request message and any transport attributes, like headers, from the transport. This might require the creation of temporary files on the file system.
3. Generate headers required by WebSphere Partner Gateway
WebSphere Partner Gateway uses special metadata to further process the document. The metadata comprises headers that the receiver constructs from the request message or the transport headers. The receiver sets one or more of following headers on the request document: The receiver request document that will be forwarded to Document Manager for further processing consists of the transport message, transport headers, and the above WebSphere Partner Gateway headers.
Note: You can execute steps, 4 and 5 in either order.
4. Do preprocessing
The receiver calls a WebSphere Partner Gateway component, the Receiver Framework, to actually do the preprocessing. The Framework executes the handlers, either supplied by WebSphere Partner Gateway or user-defined, that have been specified for this target via the Community Console, in the order they are shown in the Community Console configuration page. The Receiver Framework invokes the configured list of handlers for the target one handler after the other until one of the handlers accepts the received request document.This handler is invoked to process the receiver document. This handler can return one or more documents, and all receivers must be designed to handle multiple returns.
5. Check whether synchronous or asynchronous
The receiver calls the Receiver Framework to determine whether the received request is synchronous or not. The Framework invokes a configured list of handlers for this target, one after the other, until one of the handlers accepts the request receiver document. The Receiver Framework executes this handler to determine whether this is a synchronous request or an asynchronous request. If the handler determines that the request is asynchronous, path A will be followed. If the request is synchronous, path B will be followed.
6A. Process asynchronous request
If the request is asynchronous, (meaning that it does not require a response document to be returned to the originating trading partner) the receiver calls the Framework to process the request document. The Framework takes care of storing the information in a place from which Document Manager will retrieve it.
6B. Process synchronous request
If the request is synchronous (meaning that it requires a response document to be returned to the originating trading partner) the receiver calls the Framework to process the request document. There are two possible types of synchronous requests: blocking and nonblocking. In blocking mode, the receiver's calling thread will be blocked until the Framework returns the response document to it from Document Manager. In nonblocking mode, the receiver's calling thread will return immediately. When the Framework receives the response document at a later time, it will call the processResponse method on the receiver to pass the response document back. A correlation object is used to synchronize the originating request with this response.

Note that the JMS receiver has been migrated to the user-exit Receiver Framework and enhanced to support the handling of synchronous request-responses. Perform the following steps to use the synchronous behavior in the JMS receiver.

  1. Configure the back-end application to set the ReplyTo queue and Correlation ID in the JMS headers. When the JMS receiver receives the synchronous response from the Document Manager, it writes the response to the ReplyTo queue and the Correlation ID in the JMS headers.
  2. Configure the SyncCheck handler, either a WebSphere Partner Gateway default sync-check handler or a user-defined sync-check handler, for the JMS receiver target in the Community Console. When invoked, the configured handler returns true or false based on the received request. If the handler is the default sync check handler, it always returns true.
7. Do postprocessing
In the case of a synchronous request, the receiver calls the Receiver Framework to execute postprocessing on the response document before it is returned to the originating partner. The Receiver Framework invokes a configured list of handlers for this target one after the other until one of the handlers accepts the response receiver document. The Receiver Framework executes this handler to process the response receiver document.
8. Complete processing
In case of a synchronous request, the response document is returned to the originating trading partner over the transport. The receiver calls the setResponseStatus method on the Framework to report on the success or failure of the response delivery. The receiver removes the request message from the transport.

Exceptions

Errors can occur in the following circumstances:

If any of these failures occurs, the receiver can perform the following actions:

Reject the message from the transport
The message must be removed from the transport. In the case of a JMS receiver, for example, the message is removed from the queue. In the case of an HTTP receiver, a 500 status code is returned to the trading partner.
Archive the rejected message
This is an optional step. The message is archived, either in a queue to be resubmitted later or in a folder for rejected messages on the local file system.
Generate an event
This is an optional step. Receiver developers can choose to have receivers produce events, alerts, or both in the case of error conditions. For example, if in a synchronous request the receiver is unable to return a response document it has received from the Framework to the originating trading partner, an error event is logged. A list of events available for logging problems in the receiver stage is presented in the following chapter about APIs.

Receiver types

There are two general types of receivers, based on how they detect incoming messages on the transport. Some receivers are polling based. They poll their transports at regular intervals to determine if new messages have arrived. WebSphere Partner Gateway-supplied examples of this type of receiver include JMS, file, POP3, FTP/S Scripting, and FTP. Other receivers are callback based. They receive notification from the transport when messages arrive. The HTTP receiver is an example of a callback-based receiver.

Note: Receivers can be deployed in a multiple-box mode. In this case, multiple receivers and their configured targets might be picking up messages from the same transport location. In such a deployment model, there must be concurrent management access coordination built into the receiver.

Multiple box deployment

Receivers can be deployed in a multiple box (multi-box) mode. In this scenario, multiple receivers and their configured targets can pick up messages from the same transport location. In such a deployment model, there needs to be concurrent management access coordination built into the receiver.

In a deployment model where receiver components are deployed on multiple boxes, all the defined receivers exist on the each of the boxes. These receivers get the list of configured targets from the database, which are created from the Community Console. The target configuration must be accessible to each receiver instance; if it is not, the receiver instances fail to receive the document from that target. In some cases, the target has to be created in each of the receiver boxes.

For example, if you have a receiver component running on two boxes with a configured JMS receiver and target (MyJMSTarget) going to a queue, such as MyQueue, both the JMS receiver instances will poll the target called MyJMSTarget, which is configured with the queue 'MyQueue'. In this case, the JMS bindings file that is configured with the target is accessible to both the JMS receiver instances; for example, the bindings file kept in a shared location or the same bindings file kept in each of the boxes. This same deployment model is also applicable for the File and FTP receivers.

Copyright IBM Corp. 2003, 2005