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:
- BCGDocumentConstants.BCG_RCVR_DESTINATION: A destination type (such as production or test) associated with a target and set by receivers on a ReceiverDocumentInterface
object upon receiving the document from the target. The destination
type configured for the target can be read from the receiver configuration
by using the BCGDocumentConstants.BCG_TARGET_DESTINATION attribute.
- BCGDocumentConstants.BCG_RCVD_IPADDRESS: The host IP address where the document is received.
- BCGDocumentConstants.BCG_INBOUND_TRANSPORT_CHARSET: The character set that is obtained from the transport headers.
- BCGDocumentConstants.BCG_REQUEST_URI: The URI of the target on which the request is received.
- BCGDocumentConstants.BCG_RCVD_DOC_TIMESTAMP: The time when the document was received.
- BCGDocumentConstants.BCG_RCVD_CONTENT_LENGTH: The size of the received content.
- BCGDocumentConstants.BCG_RCVD_MSG_LNGTH_INC_HDRS: The size of the received content including headers.
- BCGDocumentConstants.BCG_RCVD_CONTENT_TYPE: The content type of the request.
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:
- Retrieval of message from transport fails
- Call to preprocess fails
- Sync check fails
- Call to carry out asynchronous or synchronous processing fails
- Call to postprocess response document fails
- Attempt to return response document on transport fails
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.
