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 24 illustrates SOAP/HTTP protocol listener processing for a synchronous operation.

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


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

Figure 25. 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.

Table 27 summarizes the order of precedence of rules used by the listener to determine the Charset, MmeType, ContentType and Content-Type header for inbound messages.


Table 27. SOAP/HTTP(s) protocol listener processing rules for inbound message

Order of Precedence Charset MimeType ContentType Content-Type header
1 Charset parameter value from the incoming HTTP message Content-Type header value URLsConfiguration connector property value for this listener Incoming HTTP message type/subtype value from the Content-Type header value Incoming HTTP message Content-Type header
2 URLsConfiguration property value for this listener SOAPDHMimeType connector property value

3 If the type of the request message ContentType is text with any subtype (for example, text/xml, text/plain, etc.), default to ISO-8859-1. Otherwise, charset will not be used. Default to ContentType

As shown in Table 27:

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.

Table 28 summarizes the order of precedence for rules used by the listener when determining the Charset, MimeType, ContentType, and Content-Type header for response messages.


Table 28. SOAP/HTTP(s) protocol listener processing rules for outbound synchronous response message

Order of Precedence Charset MimeType ContentType Content-Type header
1 Protocol ConfigMO Content-Type Header MimeType property in the TLO Protocol ConfigMO Content-Type header Protocol ConfigMO Content-Type header
2 The Charset property value in the TLO The request message MimeType, but only if the request and response ContentType match. Request message ContentType Construct Content-Type Header using ContentType and Charset
3 The request message Charset, but only if the request and response ContentType match. SOAPDHMimeType connector property value

4 If the ContentType is text/*, default to ISO-8859-1. Otherwise, charset will not be used. Use ContentType value as the MimeType

As shown in Table 28:

The listener processes the HTTP Protocol Config MO. It is the responsibility of collaboration to ensure that the header values passed in the HTTP Protocol Config MO are correct in the context of the request-response event. The listener populates standard headers and custom properties according to the following rules:

  1. The listener will investigate each item of the HTTP Protocol Config MO in order to ignore special attributes (such as ObjectEventId).
  2. Each non-empty header will be put on the outgoing message and additional processing (for example, the Content-Type header) may take place.
  3. Please note that with the above approach, the listener may set non-standard headers on the message, but will not check that the message is logically or semantically correct.
  4. If there are one or more custom properties in the HTTP Protocol Config MO UserDefinedProperties attribute, the listener will add them in the Entity Headers Section (the last headers section). For more on custom properties, see User-defined properties for event processing.

Note:
Specifying any of the following headers in the HTTP Protocol Config MO is very likely to result in an incorrect HTTP message: Connection, Trailer, Transfer-Encoding, Content-Encoding, Content-Length, Content-MD5, Content-Range.

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.

Unsupported SOAP/HTTP protocol listener processing features

The SOAP/HTTP protocol listener does not support the following:

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 26 shows SOAP/JMS protocol listener processing for a synchronous operation. The figure does not show JMS provider information.

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


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

Figure 27. 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 (JMSCorrelationID, JMSMessageID, JMSPriority, JMSExpiration, JMSDeliveryMode, JMSReplyTo, JMSTimeStamp, 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:

JMS Message Payload Type The listener will determine the payload type of the incoming message and store the information in the MessageType attribute of the JMS Protocol Config MO. The payload can be a TextMessage or BytesMessage. In TextMessage format, the listener invokes the data handler through String APIs with the web service request message extracted as a String. In the case of BytesMessage, the listener invokes the data handler via the Bytes Data Handler APIs with the web service request message extracted as a byte array.

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 42 shows the mapping between the attributes in the Protocol Config MO and the JMS message headers.

Table 29. JMS header-Protocol Config MO attribute mapping

Protocol Config MO attribute JMS header name Description
CorrelationID JMSCorrelationID The JMSCorrelationID header from the request message
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.
Timestamp JMSTimestamp The JMSTimestamp header from the request message
Redelivered JMSRedelivered The JMSRedelivered header from the request message
Type JMSType The JMSType header from the request message
Destination JMSDestination The JMSDestination header from the request message
MessageType na The type of the request message payload. The value of this attribute is Text for TextMessage payloads, and Bytes for BytesMessage payloads.

If there are one or more custom properties in the SOAP/JMS Protocol Config MO UserDefinedProperties attribute, the listener will try to extract their values from the message and populate the UserDefinedProperties business object. For more on custom properties, see User-defined properties for event processing.

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 type of the response payload depends on the value of the MessageType attribute in the JMS Protocol Config MO of the SOAP Response business object. If the MessageType is Text, the listener converts the SOAP Response business object into a String through String data handler APIs. If the MessageType is Bytes, the listener converts the SOAP Response business object into a bytes array via the Bytes data handler APIs. (The default message payload type is that of the corresponding synchronous request.) 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 or BytesMessage (depending on the MessageType determined earlier), setting the headers shown in Table 30.


Table 30. 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
JMSRedelivered The JMSRedelivered of the request message
JMSReplyTo The JMSReplyTo of the request message
JMSTimestamp The JMSTimestamp of the request message
JMSType The JMSType of the request message

The listener will set JMS Custom Properties in the response message if they are present in the Response or Fault business objects' JMS Protocol Config MO UserDefinedProperties attribute.

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 31. 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, 2004