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.
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. Using the MimeType TLO attribute, the protocol handler invokes the SOAP 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.
The SOAP/HTTP(S) protocol handler performs as described in Protocol handlers with exceptions noted in this section. Figure 27 shows the SOAP/HTTP-HTTPS protocol handler for a synchronous operation.
Figure 27.
SOAP/HTTP-HTTPS protocol handler: synchronous request
processing
Figure 28 shows the SOAP/HTTP-HTTPS protocol handler for an asynchronous request process
Figure 28.
SOAP/HTTP-HTTPS protocol handler: asynchronous request
processing
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.
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.
The SOAP/JMS protocol handler performs as described in Protocol handlers with exceptions noted in this section.
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 27.
Table 27. Header values set by SOAP/JMS protocol handler in request message
JMS header name | Value |
JMSPriority | 4 |
JMSExpiration | 0 |
JMSDeliveryMode | PERSISTENT |
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 29 shows SOAP/JMS protocol handler processing for a synchronous request operation.
Figure 29.
SOAP/JMS protocol handler: synchronous request
processing
Figure 30 shows SOAP/JMS protocol handler processing for an asynchronous request operation.
Figure 30.
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 28 shows this mapping.
Table 28. Protocol Config MO--JMS header attribute mapping
Protocol Config MO attribute | JMS header name | Description |
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 |
The SOAP/JMS protocol handler then returns the TLO to the collaboration.