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:
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:
- InboundCharSet: the inbound document character set
- MsgLengthIncHeaders: the length of the message, including
the transport headers
- requestURI: in the case of HTTP, the URI of the received
servlet
- timestamp: the received document timestamp
- fromIP: the IP address of the destination where the
document is sent
- certDN: the DN name of the SSL client certificate
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.
Error conditions can occur in the following circumstances:
- Retrieval of message from transport fails
- Call to pre-process fails
- Sync check fails
- Call to carry out async or sync processing fails
- Call to post-process response document fails
- Attempt to return response document on transport fails
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.
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 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.
