Request processing

You use the request processing capability of the connector to enable a collaboration to invoke a web service. The development tasks include using the WSDL ODA to generate a web services top-level object (TLO) and configuring a collaboration to deploy it. For further information, see Enabling collaborations for request processing. You must also configure the connector and its request processing components: the protocol handler framework and protocol handlers.

At run time, the connector receives requests from the collaboration in the form of business objects. The business objects-- SOAP Request, and optionally SOAP Response and SOAP Fault business objects-- are contained by the TLO generated by the WSDL ODA and issued by a collaboration that is configured to use web services. The TLO and its child business objects contain attributes and ASI that specify the processing mode (synchronous or asynchronous), the data handler mime type, which protocol handler to use, as well as the address of the target web service. The protocol handler uses this information to invoke an instance of the SOAP data handler, convert the Request business object to a SOAP request message, and invoke the target web service. If the mode is synchronous, the protocol handler again invokes the data handler to convert the response message into a SOAP Response business object and returns this to the collaboration.

In response to a SOAP request message, the connector can receive any of the following from the remote trading partner:

Protocol handlers play a key role in request processing.

Protocol handlers

A collaboration can invoke a web service over HTTP, HTTPS, or JMS transports. The connector has two protocol handlers and corresponding channels:

The protocol handler framework manages the protocol handlers, loading them at startup time. When the connector receives a Request business object, the request thread (note that each collaboration request comes in a thread of its own) invokes the protocol handler framework to process the request.

The protocol handler framework reads the TLOs Handler attribute ASI to determine which protocol handler to use. Applying a series of rules (see SOAP/HTTP-HTTPS protocol handler processing and SOAP/JMS protocol handler processing), the protocol handler invokes a data handler to convert the Request business object into a SOAP request message. The protocol handler packages the request message into the transport--HTTP(S) or JMS-- message. If it finds SOAPAction ASI in the Request business object, the protocol handler adds this to the request message header.

The protocol handler then reads the Destination attribute of the Request business object Protocol Config MO to determine the target address. The protocol handler then invokes the target web service with the request message.

Reading the ws_mode TLO ASI, the protocol handler determines whether the processing mode is synchronous or asynchronous. If this ASI is set to asynch, the protocol handler processing is completed. Otherwise the protocol handler waits for a response message. If a response message arrives, the protocol handler extracts the protocol headers and the payload. It then invokes the data handler (indicated by the MimeType TLO attribute) to convert the message into a Response or Fault business object. Again using the Protocol Config MO, the protocol handler sets the protocol headers in the business object. The protocol handler then returns the Response or Fault business object to the collaboration.

Depending on connector configuration, there may be one or more protocol handlers plugged into the connector. Connector-specific properties allow you to configure protocol handlers.

SOAP/HTTP-HTTPS protocol handler processing

The SOAP/HTTP(S) protocol handler performs as described in Protocol handlers with exceptions noted in this section. Figure 28 shows the SOAP/HTTP-HTTPS protocol handler for a synchronous operation.

Figure 28. SOAP/HTTP-HTTPS protocol handler: synchronous request processing

Figure 29 shows the SOAP/HTTP-HTTPS protocol handler for an asynchronous request process

Figure 29. SOAP/HTTP-HTTPS protocol handler: asynchronous request processing

Note:
This section describes SOAP/HTTP protocol handling only.

The SOAP/HTTP-HTTPS protocol handler uses the object-level ASI (cw_mo_http) of the SOAP Request business object to determine the Protocol Config MO. The SOAP/HTTP-HTTPS protocol handler determines the URL of the target web service by reading the Destination attribute in the HTTP Protocol Config MO. If the URL is missing or is incomplete, the protocol handler fails the service call. For further information on the HTTP Protocol Config MO and its attributes, see HTTP Protocol Config MO for request processing.

The SOAP/HTTP-HTTPS protocol handler invokes the web service using the SOAP request message returned by the SOAP data handler. If HTTP Proxy connector configuration properties are specified, the SOAP/HTTP(S) protocol handler behaves accordingly. If a response is returned, the SOAP/HTTP(S) protocol handler reads it.

Table 32 summarizes the order of precedence of rules used by the SOAP/HTTP-HTTPS protocol handler to determine the Charset, MimeType, ContentType, and ContentType header for outgoing request messages.

Table 32. SOAP/HTTP-HTTPS protocol handler processing rules for outbound messages

Order of Precedence Charset MimeType ContentType ContentType header
1 Protocol Config MO's Content-Type Header MimeType property in TLO attribute Protocol Config MO's Content-Type Header Protocol Config MO's Content-Type Header
2 Charset property in TLO attribute Default to ContentType Default to text/xml Construct Content-Type header using ContentType and Charset
3 If the ContentType is text/*, default to ISO-8859-1. Otherwise, charset will not be used.


As shown in Table 32:

Table 34 summarizes the order of precedence for rules used by the handler when determining the Charset, MimeType, ContentType, and ContentType header for response messages.

Table 34. SOAP/HTTP(s) protocol handler processing rules for inbound synchronous response message

Order of Precedence Charset MimeType ContentType ContentType header
1 Charset parameter value from the incoming HTTP message Content-Type header value Message TransformationMap child business object in the Request business object's Protocol Config MO Incoming HTTP message type/subtype value from the Content-Type header value Incoming HTTP message Content-Type header
2 Message TransformationMap child business object in the Request business object's Protocol Config MO The request message MimeType, but only if the request and response ContentType match.

3 The request message Charset, but only if the request and response ContentType match. MimeType property in TLO

4 Charset property in TLO. Default to ContentType

5 If the Content-Type is text/*, default to ISO-8859-1. Otherwise, Charset is not used.


As shown in Table 34:

The handler processes the HTTP Protocol Config MO. It is the responsibility of the 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 handler populates standard headers and custom properties according to the following rules:

  1. The handler 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 handler may set non-standard headers on the message, but will not guarantee 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 handler will add them in the Entity Headers Section (the last headers section). For more on custom properties, see User-defined properties for request processing.
Note:
Specifying any of the following headers in the HTTP Protocol Config MO is very likely to result in incorrect HTTP messages: Connection, Trailer, Transfer-Encoding, Content-Encoding, Content-Length, Content-MD5, Content-Range.

SOAP/JMS protocol handler processing

The SOAP/JMS protocol handler performs as described in Protocol handlers with exceptions noted in this section.

Note:
If the LookupQueueUsingJNDI configuration property is set to true, the SOAP/JMS protocol handler uses the JNDI to look up the destination 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.

The SOAP/JMS protocol handler creates a JMS transport message using the body of the web service request message returned by the SOAP data handler and with JMS headers set as shown in Table 35..

Table 35. Header values set by SOAP/JMS protocol handler in request message

JMS header name Default value if not set in SOAP/JMS Protocol Config MO
JMSPriority 4
JMSExpiration 0
JMSDeliveryMode PERSISTENT
JMSReply
JMSCorrelationId
JMSRedelivered
JMSTimestamp
JMSType

If the target web service is invoked asynchronously, the JMSReplyTo header is not set. Otherwise (for synchronous processing), the SOAP/JMS protocol handler sets the JMSReplyTo header. Using the ReplyToQueue configuration property, the SOAP/JMS protocol handler obtains the JMSDestination--the return destination for a response or fault from the target web service-- and sets it on the JMSReplyTo header on the JMS transport message.

Figure 30 shows SOAP/JMS protocol handler processing for a synchronous request operation.

Figure 30. SOAP/JMS protocol handler: synchronous request processing

Figure 31 shows SOAP/JMS protocol handler processing for an asynchronous request operation.

Figure 31. SOAP/JMS protocol handler: asynchronous request processing

The SOAP/JMS protocol handler uses object-level ASI (cw_mo_jms) of the SOAP Request business object to determine the Protocol Config MO. The Destination attribute of the Protocol Config MO gives the queue name of the target web service. If JNDI is enabled, the SOAP/JMS protocol handler obtains the JMSDestination for the SOAP request message by looking up the JNDI object. Otherwise it uses the Destination attribute in the SOAP Protocol Config MO.

If the response does not arrive in the interval specified in the ResponseWaitTimeout property, the SOAP/JMS protocol handler fails the collaboration request. On arrival of the SOAP response (or fault) message, the SOAP/JMS protocol handler extracts the JMS headers and payload for conversion by the SOAP data handler. The SOAP/JMS protocol handler then sets the SOAP Response (or Fault) business object in the TLO, using the Protocol Config MO in the Response (or Fault) business object to map the JMS headers. Table 36 shows this mapping.

Table 36. Protocol Config MO--JMS header attribute mapping for response during synchronous request processing

Protocol Config MO attribute JMS header name Description
Destination JMSDestination The JMSDestination header from the response message.
MessageId JMSMessageId The JMSMessageId header from the response message
Priority JMSPriority The JMSPriority header from the response message
Expiration JMSExpiration The JMSExpiration header from the response message
DeliveryMode JMSDeliveryMode The JMSDeliveryMode header from the response message
ReplyTo JMSReplyTo The JMSReplyTo header from the response message. The JMS API returns this header as JMSDestination, but the SOAP/JMS protocol listener returns the queue name.
CorrelationId JMSCorrelationId The JMSCorrelationId header from the response message
Redelivered JMSRedelivered The JMSRedelivered header from the response message
TimeStamp JMSTimeStamp The JMSTimeStamp header from the response message
Type JMSType The JMSType header from the response message

The SOAP/JMS protocol handler then returns the TLO to the collaboration.

Copyright IBM Corp. 1997, 2003