Configuring the SOAP data handler

The SOAP data handler is a pivotal component in the connector for web services. The connector calls the SOAP data handler to transform business objects into web services-compliant SOAP messages.

When collaborations are exposed as web services, the connector also calls the SOAP data handler. The data handler then transforms SOAP messages sent from a remote trading partner (or internal client) into business objects. The connector passes the business objects to collaborations that have been configured for web services.

The information in data handler meta-objects plays a crucial role in these transformations. You configure this information after you install the product files, but before startup. Unless you are adding a custom name handler, you can use the default SOAP data handler configuration to save time. You must, however, configure specific meta-object information for each data handler transformation. Data handler meta-objects are discussed in the sections below.

Meta-object requirements

Meta-objects are business objects that contain configuration information. The connector uses meta-objects at runtime to configure the data handler and create instances of it. The SOAP data handler also uses meta-objects to locate the body of a SOAP message, to determine the business object and verb that the body corresponds to, to encode a business object in a SOAP message, and to perform a number of other tasks discussed in this chapter. This section describes requirements for these meta-objects.

Meta-object hierarchy and terminology

Figure 27 shows the meta-object structure for the adapter for web services product. The meta-objects are named in bold in the illustration and discussed below.

Figure 39. Meta-object structure

The following terminology is used throughout this document when discussing meta-objects:

MO_DataHandler_Default

The MO_DataHandler_Default is the top-level meta-object for all data handlers that are called from connectors. The MIME type contained in these meta-objects determines which data handler to use. The connector agent uses this meta-object to create instances of the SOAP data handler. Accordingly, the MO_DataHandler_Default object must include an attribute named xml_soap that is of type MO_DataHandler_DefaultSOAPConfig.

You can configure the MO_DataHandler_Default object after installing it. You must add xml_soap of type MO_DataHandler_DefaultSOAPConfig.

MO_DataHandler_DefaultSOAPConfig

The connector agent uses this meta-object to create and configure the SOAP data handler at runtime. The MO_DataHandler_DefaultSOAPConfig has two attributes of type string that designate:

These attributes are shown in Table 35.

Unless you wish to implement a custom name handler, which is discussed later in this chapter, you can use the MO_DataHandler_DefaultSOAPConfig as delivered and installed. No configuration is needed.

Table 35. Meta-object attributes for MO_DataHandler_DefaultSOAPConfig

Name Type Default value Description
ClassName String com.ibm.adapters .dataHandlers.xml. soap Standard attribute used by the data handler base class to find the class name based on a MIME type passed into the createHandler method.
SOAPName
Handler
String
Name of the SOAP name handler to use.

SOAP configuration meta-object: child of every SOAP business object

A SOAP Config MO defines the data formatting behavior for one data handler transformation -- either a SOAP-message-to-business-object or business-object-to-SOAP-message transformation. A SOAP Config MO is a child of a SOAP business object. These child SOAP Config MOs are critical for default business object resolution. When using default business object resolution, all child SOAP Config MOs, whether for a request, response, or fault object, must have unique entries for default values of BodyName and BodyNS. Table 36 shows these and other attributes of a SOAP Config MO.

Table 36. Attributes for SOAP Config MOs

Name Required Description
BodyNS Yes Namespace to be used for SOAP body.
BodyName Yes Name of the body of the SOAP message. For SOAP fault, set the default value to soap:fault.
BOVerb Yes Verb of the business object that contains the SOAP Config MO.
TypeInfo No True or false attribute that dictates whether type information (xsi:type) is written to and read from a SOAP element. Default = false
TypeCheck No This property is read only if TypeInfo is set to true. Possible values are none and strict. If none, type validation is skipped when reading SOAP messages into this business object. If strict, the data handler will strictly validate all SOAP type names and namespaces against the business object's application-specific information. Default = none
Style No This property dictates the SOAP message style and has implications for other attributes such as BodyName and BodyNS. The possible values for this attribute are rpc and document. Default = rpc
Use No This property dictates the SOAP message's use and affects how the SOAP body is constructed from a business object. The possible values are literal and encoded. The default is literal.

Figure 40 shows the relationship between a SOAP business object and a SOAP Config MO.

Figure 40. SOAP configuration meta-object

Figure 40 shows a SOAP response business object and its child business object. The child business object, SOAPCfgMO, is a SOAP Config MO that specifies the behavior for the SOAP data handler for a transformation from a business object response to a SOAP response message. The attribute indicating the child SOAP Config MO must use the name-value pair beginning cw_mo_soap.

By convention, when reading business object level application-specific information beginning with cw_mo_, the data handler recognizes that the child object specified in the name-value pair contains transformation meta-object information and therefore does not include this child as content in the body of the message it is transforming. In the example, the child objects indicated by the name-value pairs cw_mo_jms and cw_mo_soap are recognized as meta-objects and not written into the SOAP response message. In addition, the SOAP data handler ignores all business object level application-specific information beginning with cw_mo_ except for cw_mo_soap. Accordingly, the SOAP data handler ignores the application-specific information such as cw_mo_tpi. But the SOAP data handler reads and uses the SOAP Config MO specified in cw_mo_soap to execute the SOAP response transformation from business object to SOAP message.

All SOAP business objects must have child SOAP Config MOs and these must be specified as application-specific information at the business object level. Much of this is automated: when you use the WSDL ODA to generate business objects for SOAP messages, the SOAP Config MOs are automatically generated for you.

Style and Use impact on SOAP messages

The SOAP Config MO optional properties, Style and Use, affect the way that SOAP messages are created. The possible values for Style are rpc and document, and for Use are literal and encoded. The sections below discuss how the Style and Use combinations impact SOAP message creation.

rpc/literal

When the Style property is set to rpc and the Use property to literal, the Body Name and Body Namespace for a SOAP Message are read from the SOAP ConfigMO's BodyName and BodyNS properties, respectively.

The following is an example of an rpc/literal style message where the Body Name and Body Namespace have been resolved to getOrderStatus and OrderStatusNS respectively:

<?xml version='1.0' encoding='UTF-8'?>
 <SOAP-ENV:Envelope xmlns:SOAP-ENV=îhttp://schemas.xmlsoap.org/soap/envelope/ì 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
       <ns1:getOrderStatus xmlns:ns1="http://www.ibm.com/">
          <Part1>
             <ns2:Elem1 xmlns:ns2="http://www.ibm.com/elem1">
                <Child1>1</Child1>
                <Child2>2</Child2>
             </ns2:Elem1>
             <ns3:Elem1 xmlns:ns3="http://www.ibm.com/elem1">
                <Child1>3</Child1>
                <Child2>4</Child2>
             </ns2:Elem1>
             <Elem2>10</Elem2>
          </Part1>
       </ns1:getOrderStatus>
    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
  
  
  
 

Figure 41 shows the corresponding business object for this rpc/literal message.

Figure 41. rpc/literal SOAP Config MO

Note:
You must configure these properties and business object attributes appropriately so that a corresponding SOAP message is created.
rpc/encoded

When the Style property is set to rpc and Use is set to encoded, the Body Name and Body Namespace for a SOAP Message are read from the Child ConfigMO's BodyName and BodyNS properties respectively. Also, the SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" attribute is added to the Body tag.

The following is an example of an rpc/encoded message where the Body Name and Body Namespace have been resolved to getOrderStatus and OrderStatusNS respectively.

<?xml version='1.0' encoding='UTF-8'?>
 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body SOAP-ENV:encodingStyle=
     "http://schemas.xmlsoap.org/soap/encoding/">
       <ns1:getOrderStatus xmlns:ns1="http://www.ibm.com/">
          <Part1 xsi:type="ns1:SOAP_Part1Type">
             <ns2:Elem1 SOAP-ENC:arrayType="ns2:SOAP_MaxType[2]" 
              xsi:type="SOAP-ENC:Array" xmlns:ns2="http://www.ibm.com/elem1">
                <item>
                   <Child1 xsi:type="xsd:string">1</Child1>
             <Child2 xsi:type="xsd:string">2</Child2>
                </item>
                <item>
                   <Child1 xsi:type="xsd:string">3</Child1>
             <Child2 xsi:type="xsd:string">4</Child2>
                </item>
             </ns2:Elem1>
             <Elem2 xsi:type="xsd:string">10</Elem2>
          </Part1>
       </ns1:getOrderStatus>
    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
  
  
 

Figure 42 shows the corresponding business object for this rpc/encoded message.

Figure 42. rpc/encoded SOAP Config MO

document/literal

When the Style property is set to document and the Use property is set to literal, an all encompassing Body Name tag will not exist. This is an example of a document style SOAP message based on the above BO:

<?xml version='1.0' encoding='UTF-8'?>
 <SOAP-ENV:Envelope xmlns:SOAP-ENV=
 "http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
       <ns1:Elem1 xmlns:ns1="http://www.ibm.com/elem1">
          <Child1>1</Child1>
          <Child2>2</Child2>
       </ns1:Elem1>
       <ns2:Elem1 xmlns:ns2="http://www.ibm.com/elem1">
          <Child1>3</Child1>
          <Child2>4</Child2>
       </ns2:Elem1>
    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
  
 

Figure 43 shows the corresponding business object for this document/literal message.

Figure 43. document/literal SOAP Config MO

Note that the encodingStyle attribute in the XML code fragment has not been set.

document/encoded

This Style/Use combination is not supported. The data handler fails if it encounters a SOAP ConfigMO with Style set to document and Use set to encoded.

Copyright IBM Corp. 2003