Event processing

The first step in implementing an event processing capability is exposing a business process -- a collaboration -- as a web service. You then publish this web service, in a UDDI registry, for example, and configure the connector to respond to web service clients that invoke the collaboration.

During event processing, the connector uses protocol listeners and the SOAP data handler to convert SOAP request messages from web service clients to business objects that can be manipulated by collaborations that have been exposed as web services. Protocol listeners play a crucial role in event processing.

Protocol listeners

Web Service requests may come over variety of transports, including HTTP, HTTPS, and JMS. The Web Services protocol listener monitors the arrival of such requests on its transport channel. There are three protocol listeners and corresponding channels:

Each of these consists of a thread that listens on its transport. When it receives a SOAP request message from a client, the listener registers the event with the protocol listener framework.

The protocol listener framework manages the protocol listeners, scheduling requests as resources are available. You configure the listeners and aspects of the protocol listener framework when you set values to connector-specific properties. Among the protocol listener framework properties you can configure are the following:

These two connector-specific properties control memory allocation in a way that prevents protocol listeners from clogging the connector with infinite web service events. The allocation algorithm is as follows: At any time, the connector can receive a total number of events equal to WorkerThreadCount + RequestPoolSize. It can process WorkerThreadCount number of requests in parallel.

You can plug additional protocol listeners into the protocol listener framework. For further information, see Creating multiple protocol listeners andConnector-specific configuration properties.

SOAP/HTTP and SOAP/HTTPS protocol listener processing

The SOAP/HTTP(S) protocol listener consists of a thread that continuously listens for HTTP(S) requests from web service clients. The listener thread binds the host and port that are specified in the Host and Port connector-specific configuration (listener) properties. Another configuration property--RequestWaitTimeout--defines the interval during which the listener waits for a request before checking whether the connector has shut down.

Figure 23 illustrates SOAP/HTTP protocol listener processing for a synchronous operation.

Figure 23. SOAP/HTTP protocol listener: synchronous event processing


Figure 24 shows SOAP/HTTP protocol listener processing for an asynchronous operation.

Figure 24. SOAP/HTTP protocol listener: asynchronous event processing


When a web services client initiates a SOAP/HTTP or SOAP/HTTPS request, it posts a SOAP request message to the URL of the SOAP/HTTP or SOAP/HTTPS listener. The client should use the HTTP POST method to invoke the protocol listener URL.

When an HTTP(S) request arrives, the listener registers the request with protocol listener framework, which schedules the event for processing as resources become available. The listener then extracts the protocol headers and the payload from the request. Using the SOAPDHMimeType connector configuration property, the listener invokes the SOAP data handler to convert the request message into a SOAP Request business object.

If the collaboration is invoked asynchronously, the listener delivers the request business object to the integration broker and responds to the web services client with the HTTP status code 202 Accepted. This concludes listener processing.

If it is a synchronous invocation, the listener invokes the collaboration synchronously. The collaboration responds with a SOAP Response business object. The listener then invokes the SOAP data handler to convert the Response business object returned by the Collaboration into a SOAP response message. The listener delivers the response message to the web service client and includes a 200 OK HTTP status code. If the collaboration returns a SOAP Fault business object, it is converted to a Fault message. This fault message is delivered to the web service client with a 500 Internal Server Error HTTP code.

The listener then closes the connection and the thread that processed the event becomes available.

SOAP/HTTPS listener processing using secure sockets

SOAP/HTTPS protocol listener processing is the same as that described in the SOAP/HTTP protocol listener processing section except that HTTPS uses secure sockets. For further information, see SSL.

SOAP/JMS protocol listener processing

The SOAP/JMS protocol listener consists of a thread that continuously listens on the InputQueue, which is the JMS destination for requests from web service clients. The RequestWaitTimeout connector configuration property defines how long the listener will wait for a request before checking whether the connector has shut down.

Figure 25 shows SOAP/JMS protocol listener processing for a synchronous operation. The figure does not show JMS provider information.

Figure 25. SOAP/JMS protocol listener: synchronous event processing


Fig shows SOAP/JMS protocol listener processing for an asynchronous operation.

Figure 26. SOAP/JMS protocol listener: asynchronous event processing


Note:
If the LookupQueueUsingJNDI configuration property is set to true, the SOAP/JMS protocol listener uses the JNDI to look up the queue. The JNDI properties are specified in connector properties. For further information, see Connector and JMS and the JNDI-related properties in Connector-specific configuration properties.
When a web service client initiates a SOAP/JMS request, it sends a SOAP request message to the InputQueue on which the SOAP/JMS listener is listening. When it receives the SOAP request message from the InputQueue, the SOAP/JMS protocol listener registers the request with the protocol listener framework. The protocol listener framework schedules the request as and when resources are available.
Note:
If the connector configuration property IndoubtEvents is set to Reprocess, the protocol listener framework will schedule JMS messages from the InProgressQueue before scheduling messages from the InputQueue.

The listener then dispatches this message--the body as well as the required JMS headers (JMSMessageID JMSPriority, JMSExpiration, JMSDeliveryMode, JMSReplyTo, JMSType)-- to the InProgressQueue. The protocol listener framework then registers the event.

The listener then reads the JMS message from the InProgressQueue, extracting the body of the message and the following headers:

The JMSType must be set to TextMessage or the listener will fail to process the request. If the JMSType is not set to TextMessage and the JMSReplyTo header is specified, the listener responds with a SOAP fault message, setting the faultcode to Client and setting the faultstring to Cannot handle non-text JMS Body.

Using the SOAPDHMimeType connector configuration property, the listener invokes the SOAP data handler to convert the request message into a SOAP Request business object. If errors occur during conversion and the JMSReplyTo JMS header is specified, the listener responds with a SOAP fault message, setting the faultcode to Client and the faultstring to Cannot Parse. The fault message provides no other detail.

The listener uses the object-level cw_mo_jms ASI of the SOAP Request business object returned by the data handler to determine the Protocol Config MO. Note that both the ASI and the Protocol Config MO are optional for event processing. If it finds a Protocol Config MO, the listener populates it with the JMS message headers extracted earlier. Table 32 shows the mapping between the attributes in the Protocol Config MO and the JMS message headers.

Table 22. JMS header-Protocol Config MO attribute mapping
Protocol Config MO attribute JMS header name Description
MessageId JMSMessageId The JMSMessageId header from the request message
Priority JMSPriority The JMSPriority header from the request message
Expiration JMSExpiration The JMSExpiration header from the request message
DeliveryMode JMSDeliveryMode The JMSDeliveryMode header from the request message
ReplyTo JMSReplyTo The JMSReplyTo header from the request message. The JMS API returns this header as JMSDestination, but the SOAP/JMS protocol listener returns the queue name.

If the TLO (in the case of a non-TLO SOAP Request business object) is not subscribed by the integration broker, the listener logs an error. If the JMSReplyTo header is specified in the request message, the listener creates a SOAP fault message and places it on the JMSReplyTo queue. The faultcode is set to Client and the faultString is set to Not subscribed to this message. No other detail is provided in the fault message. If configured to do so, the listener also archives the original JMS request message including its JMS headers to the UnsubscribedQueue.

If the collaboration is invoked asynchronously, the listener delivers the Request business object to the integration broker. The listener then removes the message from the InProgressQueue. If configured to do so, the listener also archives the original JMS request message including its JMS headers to the ArchiveQueue.

If errors occur during asynchronous processing and JMSReplyTo is specified, the listener responds with a fault message. Its faultcode is set to Server and its faultstring is set to Internal Error. If configured to do so, the listener also archives the original JMS request message, including its JMS headers, to ErrorQueue.

If it is a synchronous invocation, the listener invokes the collaboration synchronously. The collaboration responds with a SOAP Response business object. The listener invokes the SOAP data handler to convert the Response business object returned by the Collaboration into a SOAP/JMS response message. The listener delivers the response message to the ReplyTo queue (this is provided by the JMSReplyTo header on the original request message). The listener then sets the response message returned by the data handler as a TextMessage, setting the headers shown in Table 23.


Table 23. Header values set by SOAP/JMS protocol listener in response message
JMS header name Value
JMSCorrelationId The JMSMessageId of the request message
JMSDeliveryMode The JMSDeliveryMode of the request message
JMSPriority The JMSPriority of the request message
JMSExpiration The JMSExpiration of the request message

If configured to do so, the listener then moves the original JMS message (request from the web service client), including its headers, from the InProgressQueue to the ArchiveQueue.

If errors occur and JMSReplyTo is specified, the listener responds with a fault message, and, if configured to do so, also archives the original JMS request message to the ErrorQueue.

Event persistence and delivery

Event persistence is protocol contingent:

Event sequencing

The connector may deliver events in any sequence.

Event triggering

The event triggering mechanism depends on how the protocol listener is configured.

Note:
Connector does not distinguish between Create or Update or Retrieve or Delete. All such events follow the same approach.

Event detection

Event detection is performed by each protocol listener. The event detection mechanism depends utterly on the transport and how you configure the connector-specific properties for each listener. For more on these properties, see Connector-specific configuration properties.

Event status

Event status is managed by the protocol listener and depends on the transport and also on how you configure the listener.

Event retrieval

Event retrieval is managed by the protocol listener and depends on the transport and also on how you configure the listener.

Event archiving

Event archiving is managed by the protocol listener and depends on the transport and also on how you configure the listener.

Event recovery

Event recovery is managed by the protocol listener and depends on the transport and also on how you configure the listener.


Table 24. Header values set by SOAP/JMS protocol listener in response message
InDoubtEvents value Event recovery processing
FailOnStartup If it finds events in the InProgressQueue, the listener logs a fatal error and immediately shuts down.
Reprocess If it finds events in the InProgressQueue, the listener processes those events first. The listener can trace the number of messages found in the InProgressQueue.
Ignore Events in the InProgressQueue are ignored. The listener can trace the events found in the InProgressQueue and the ignoring of those events by the listener.
LogError If it finds events in the InProgressQueue, the listener logs error and continues processing.

Copyright IBM Corp. 1997, 2003