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:
- 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 where 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 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.
- 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.
- 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:
- Retrieval of the message from the transport fails
- Call to preprocess fails
- Sync check fails
- Call to carry out asynchronous or synchronous processing fails
- Call to postprocess the 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
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.
