Overview for creating new receivers

Receivers are transport-specific. WebSphere Partner Gateway ships with receivers for FTP directory, JMS, File directory, SMTP (POP3), 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. These new receivers can be configured using the Community Console and integrated into the processing flow in the normal way. This section describes the process of developing a new receiver. It covers:

Receiver flow

The nature of 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 may 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 which will be forwarded to Document Manager for further processing consists of the transport message, transport headers, and these WebSphere Partner Gateway headers.
Note: You can execute the following 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 console, in the order they are shown in the console configuration screen. The request document is passed as input to the first handler, and then the returned processed document is fed as input to the next handler, and so on until one of the handlers accepts it. This handler is then invoked to process the receiver document. This handler may 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 then 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, (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 (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.
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 then 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 then removes the request message from the transport.

Exceptions

Error conditions can occur in the following circumstances:

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

Reject the message from 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 rejected folder on the local file system.
Generate an event
This is an optional step. Receiver developers may choose to have receivers produce events and/or alerts 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 should be logged. A listing of events available for logging problems in the receiver stage is presented in the following API chapter.

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 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 may be deployed in a multi-box mode. In this case, multiple receivers and their configured targets may be picking up messages from the same transport location. In such a deployment model, there needs to be concurrent management access coordination built into the receiver.

Receiver architecture

Receiver development is based on two major parts: the receiver itself, represented in the API by the ReceiverInterface interface and the Receiver Framework, represented in the API by the ReceiverFrameworkInterface interface. The Framework is responsible for providing an interface between the receiver and the main body of WebSphere Partner Gateway code. The receiver calls methods on the Framework to accomplish the various processing steps.

Additional components specified in the API include ReceiverConfig, a way of querying and setting the various configuration attributes created in the Community Console; ReceiverDocumentInterface, the receiver request document which the receiver creates from the transport message; ResponseCorrelation, the provided mechanism for maintaining synchronization in a nonblocking synchronous scenario; a general exception class, BCGReceiverException; and a utility class, BCGReceiverUtil, which provides static methods for getting a Framework object, creating a request document, and finding appropriate file storage information. All of these are covered in detail in the Receiver API chapter.

Copyright IBM Corp. 2003, 2005