Overview for creating new receivers

Receivers are transport specific. WBI-C ships with receivers for FTP directory, JMS, File directory, SMTP (POP3), and HTTP/S transports. To add a new transport to the WBI-C system, users can write their own receivers, using an API provided with the 4.2.2 release. 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 WBI-C required headers
There are special WBI-C headers that are used for further processing of the document. Receivers should have a mechanism for creating any of these headers that are appropriate, from transport message attributes or in other ways. The list of headers is as follows:

The receiver request document which will be forwarded to Document Manager for further processing consists of the transport message, transport headers, and these WBI-C headers.

Note: The following steps, 4 and 5, may be executed in either order.

4. Do pre-processing
The receiver calls a WBI-C component, the Receiver Framework, to actually do the pre-processing. The Framework executes the handlers, either Connect supplied 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. This step may return 1 or more documents, and all receivers must be designed to handle multiple returns.

5. Check sync status
The receiver calls the Receiver Framework to determine whether the received request is synchronous or not. The Framework moves through its configured list of handlers until an appropriate one is located. The outcome of this step determines the receiver's next step. If 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 non-blocking. In blocking mode, the receiver's calling thread will be blocked until the Framework returns the response document to it from Document Manger. In non-blocking 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 sync up the originating request with this response.

7. Do post-processing
In the case of a synchronous request, the receiver calls the Framework to execute post-processing on the response document before it is returned to the originating partner. The Framework executes the handlers, either Connect supplied 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 response 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.

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 performs the following actions:

Rejects 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.

Archives 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. In the latter case, the Framework may be able to generate the appropriate storage files for the rejected request document.

Generates event
This is an optional step. Receiver developers may choose to have receivers produce events and/or alerts in the case of error conditions. There are three levels of events: informational, warning, and error. Informational events simply provide more information to the execution flow. Warning events log problems that nonetheless do not stop the execution flow. Error events are logged when processing of document results in an error and further document processing is stopped. 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. Connect-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 WBI-C 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 sync in a non-blocking sync 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, 2004