Using application-specific information functionality

You can specify object- and attribute-level application-specific information (ASI) to extend and enhance SOAP data handler functionality. Table 45 shows these attributes, which are discussed in the sections below. All of the entries in the table are attribute-level ASI unless otherwise noted.

Table 45. SOAP object ASI summary
ASI Possible values Description
soap_location SOAPHeader Specifies this business object attribute as the header attribute
headerfault String Identifies the BO attribute name of the corresponding SOAP header in the fault BO
elem_name String Specifies the name for the SOAP element corresponding to this BO attribute
elem_ns String Specifies the namespace for the SOAP element corresponding to this BO attribute
type_name String Specifies the type for the SOAP element corresponding to this BO attribute
type_ns String Specifies the type namespace for the element corresponding to this BO attribute
xsdtype true Specifies xsd as the namespace for the element corresponding to this BO attribute, overriding older xsd versions (such as 1999, 2000, etc.) with the latest version of xsd (for example, 2001).
attr_name String Specifies the name for the SOAP attribute corresponding to this BO attribute
attr_ns String Specifies the namespace for the SOAP attribute corresponding to this BO attribute
arrayof String Specifies the name of the n cardinality child business object attribute that must be used as a placeholder for the simple type array items
dh_mimetype String Specifies the mimeType of the data handler that will be used to transform this attribute of complex type
cw_mo_* String This business object level ASI specifies the name of a child config MO that is interpreted as meta-data, not content, by the SOAP data handler. Only cw_mo_soap specifies a child config MO that is processed as meta-data; all other cw_mo_* indicate a different component and are therefore excluded from SOAP data handler processing. All other cw_mo* is ignored.
cw_mo_soap String This business object level ASI specifies the name of the Child Config MO attribute that should be used when transforming this business object
cw_mo_jms String This business-object level ASI specifies the name of the JMS Protocol Config MO to use
cw_mo_http String This business-object level ASI specifies the name of the HTTP Protocol Config MO to use
wrapper true Specifies the attribute name of the wrapper object within this business object. Wrapper objects are used for certain schema indicators, and must not be serialized
maxoccurs Integer Specifies this business object attribute's maximum occurrence possibility. Depending on the value of maxoccurs, the business object may or may not have a wrapper.
minoccurs Integer Specifies this business object attribute's minimum occurrence possibility. Depending on the value of minoccurs, the object may or may not have a wrapper.
all String Specifies the child attribute that represents the all indicator in the schema.
choice String Specifies the child attribute that represents the choice indicator in the schema.

ASI in business-object-to-SOAP-message transformations

The SOAP data handler uses a business object's ASI to determine how to construct a SOAP message. Unless otherwise stated, all ASI discussed in the sections below refers to attribute level ASI and all string-based comparisons are performed without regard to case.

elem_name and elem_ns processing

The examples discussed in this section assume that the attribute name is OrderId and the SOAP element namespace prefix ns0.

  1. When neither elem_name nor elem_ns are specified, the elem_name defaults to the attribute name, and the elem_ns defaults to the namespace of the element's parent.The ASI is not specified.
    <OrderId>1</OrderId>
  2. When the elem_name is specified and the elem_ns is not specified, the elem_name will be set to the ASI elem_name value, and the elem_ns will be defaulted to the namespace of the SOAP Body. The ASI is as follows:
    elem_name=CustOrderId
    <CustOrderId>2</CustOrderId>
  3. When elem_ns is specified and elem_name is not, elem_name defaults to the attribute name and elem_ns is set to the ASI elem_ns value. The xmlns attribute is explicitly written if and only if the element namespace is not found elsewhere in the scope of this element. If the element namespace is found, the already defined namespace prefix is used. Otherwise (if the element namespace is no found), a unique prefix for the elem_ns is generated. Consider the following example, which presumes that a prefix is already defined in scope (ns1 represents a prefix corresponding to a namespace already defined in the scope of this element). The ASI is as follows:
    elem_ns= http://www.w3.org/2001/XMLSchema
    <ns1:OrderId>3</ns1:OrderId>

    The following example presumes that prefix is not found (ns2 represents a unique prefix). The ASI is as follows:
    elem_ns=CustOrderIdNamespace
    <ns2:OrderId xmlns:ns2="CustOrderIdNamespace">3</ns2:OrderId>
  4. When both elem_name and elem_ns are specified, elem_name and elem_ns are set to the ASI values. The same check that is performed in case 3 above regarding already defined namespaces applies. Just as in case 3, if the namespace is not already defined, a unique prefix for the elem_ns is generated. The ASI is as follows:
    elem_name=CustOrderId;elem_ns=CustOrderIdNamespace
    <ns2:CustOrderId xmlns:ns2="CustOrderIdNamespace">1</ns2:OrderId>

type_name and type_ns processing for simple attributes

For the examples in this section, the attribute name is OrderId, the SOAP element namespace prefix is ns0, and the attribute type is String.

Note:
type_name and type_ns processing takes place only when the Config MO attribute TypeInfo is true.

  1. When neither type_name nor type_ns are specified, type_name defaults to the simple type and the type_ns defaults to the xml schema-defined namespace (xsd). The ASI is not specified
    <OrderId xsi:type="xsd:string">1</OrderId>
  2. When type_name is specified and type_ns is not, type_name is set to the ASI type_name value and type_ns defaults to the namespace of the element. The ASI is as follows:
    type_name=CustString
    <OrderId xsi:type="ns0:CustString">2</OrderId>
  3. When type_ns is specified and type_name is not, the type_ns defaults to the simple type name and type_name is set to the ASI type_ns value. The prefix is handled in a way that is comparable to elem_ns creation. A unique prefix for the type namespace is generated unless the namespace already exists in the element scope. The ASI is as follows:
    type_ns=CustStringNamespace
    <OrderId xmlns:ns2="CustStringNamespace" xsi:type=
    "ns2:String">3</OrderId>
  4. When both type_name and type_ns are specified, they are set to the assigned ASI values. A unique prefix for the type namespace is generated. The ASI is as follows:
    type_name=CustString;type_ns=CustStringNamespace
    <OrderId xmlns:ns2="CustStringNamespace" xsi:type=
    "ns2:CustString">1</OrderId>

type_name and type_ns processing for single cardinality attributes

For the examples in this section, the attribute name is OrderStaus, the SOAP element namespace prefix is ns0, and the attribute type is OrderStatus.

Note:
type_name and type_ns processing takes place only when the Config MO attribute TypeInfo is true.

  1. When neither type_name nor type_ns are specified, type_name defaults to the business object name and the type namespace defaults to the namespace of the element. The ASI is not specified:
    <OrderStatus  xsi:type="ns0:OrderStatus">1</OrderStatus>
  2. When type_name is specified and type_ns is not, the type_name is set to the assigned ASI value and type_ns defaults to the namespace of the element. The ASI is as follows:
    type_name=CustOrderStatus
    <OrderStatus  xsi:type="ns0:CustOrderStatus">1</OrderStatus>
  3. When type_ns is specified and type_name is not, type_name defaults to the business object name and type_ns is set to the assigned type_ns value. A unique prefix for the type namespace is generated. The ASI is as follows:
    type_ns=CustTypeNS
    <OrderStatus  xsi:type="ns2:SOAP_OrderStatusLine
    " xmlns:ns2="CustTypeNS">1</OrderStatus>
  4. When both type_name and type_ns are specified, they are set to the assigned ASI values. A unique prefix for the type namespace is generated. The ASI is as follows:
    type_name=CustOrderStatus;type_ns=CustTypeNS
    <OrderStatus  
    xsi:type="ns2:CustOrderStatus" xmlns:ns2="CustTypeNS">1</OrderStatus>

type_name and type_ns processing for multiple cardinality attributes

For all the examples given in this section assume the attribute name to be MultiLines and the SOAP element namespace prefix to be ns0. Assume the attribute type to be OrderStatus.

Note:
type_name and type_ns processing takes place only when the Config MO attribute TypeInfo is true.

  1. When neither type_name nor type_ns are specified, type_name defaults to the business object name and type_ns defaults to the namespace of the element. The ASI is as follows:
    <MultiLines SOAP-ENC:arrayType="ns0:OrderStatus[2]" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
    xsi:type="SOAP-ENC:Array">
  2. When type_name is specified and type_ns is not, type_name is set to the assigned ASI type_name value and type_ns defaults to the namespace of the element. The ASI is as follows:
    type_name=CustOrderStatus
    <MultiLines SOAP-ENC:arrayType="ns0:CustOrderStatus[2]" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
    xsi:type="SOAP-ENC:Array">
  3. When type_ns is specified and type_name is not, type_name defaults to the business object name, and the type_ns is set to the assigned ASI type_ns value. A unique prefix for the type namespace is generated. The ASI is as follows:
    type_ns=CustTypeNS
    <MultiLines SOAP-ENC:arrayType="ns2:OrderStatus[2]" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/
    " xmlns:ns2="CustTypeNS" xsi:type="SOAP-ENC:Array">
  4. When both type_name and type_ns are specified, they are set to the assigned ASI values. A unique prefix for the type namespace is generated. The ASI is as follows:
    type_name=CustOrderStatus;type_ns=CustTypeNS
    <MultiLines SOAP-ENC:arrayType="ns2:CustOrderStatus[2
    ]" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:ns2="CustTypeNS" xsi:type="SOAP-ENC:Array">

Note:
The item element representing the parent for each Array element has the same type and namespace as the arrayType.

xsdtype for simple, single, and multiple cardinality types

For simple, single. and multiple cardinality types, set the xsdtype ASI attribute to true for the type name to adhere to the current XSD for the SOAP message. The xsdtype property is read only when both the type_name and type_ns properties are set. Given the type_name and type_ns, the SOAP data handler first attempts to map the pair to a Java type using the SOAP API. Then the data handler attempts to convert the Java type back to a SOAP element type using the current XSD for the SOAP Message. For example, if the current XSD is

http://www.w3.org/2001/XMLSchema

and the following ASI:

type_name=timeInstant;type_ns=http://www.w3.org/1999/XMLSchema;xsdtype=true

The SOAP message type name is written as:

<OrderDate xsi:type="xsd:dateTime">

because dateTime is the 2001 XSD equivalent of the timeInstant in the 1999 XSD.

xsdtype and simple type arrays

For multiple cardinality objects, you can create a simple type array such as the following:

<MultiLines SOAP-ENC:arrayType="xsd:string[4]" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="SOAP-ENC:Array">

To achieve this, set the type_name property to the desired simple type (for example, string) and set the type_ns property to the appropriate XSD specification. Then, set the xsdtype property to true so that the type is converted to the current XSD type. Finally, the arrayOf property should be set to the name of the attribute in the container which should hold the simple type value. This is an example of what the ASI would look like for a string array:

arrayof=size;type_name=string;type_ns=http://www.w3.org/2001/XMLSchema;xsdtype=true

ASI effects on fault processing

The faultcode, faultactor, faultstring, and detail elements adhere to the following rules:

  1. Any elem_name, elem_ns, type_name and type_ns ASI in these attributes is ignored.
  2. All children of the detail elements are written exactly as described in body processing.

ASI effects on header processing

You can use all ASI properties (see Table 45) at the header child object level and below.

Specifying SOAP attributes

attr_name processing for simple types

There is an XML schema case in which complexTypes with simpleContent extensions or restrictions have have both values and attributes. For example, consider the following SOAP tag:

<size system="us">10</size>

It is based on the following schema:

<complexType name="SizeType">
   <simpleContent>
       <extension base="int">
          <attribute name="system" type="string"/>
       </extension>
   </simpleContent>
</complexType>
<element name="size" type="ns:SizeType"/>

The business object corresponding to the complex type, with simple content extension or restriction, must contain one additional attribute besides other attributes that correspond to the complex type attributes. The additional attribute must contain the simple content value (in the example above, 10-- the value of element size). The business object attribute, having the business object corresponding to such a complex type as its type, will have elem_value=simpleContentValue as its attribute-level ASI.

Figure 45 shows the corresponding business object.

Figure 45. attr_name business object for simple types

attr_name processing for single and multiple cardinality types

You can specify ASI that translates business object attributes into soap attributes instead of into soap elements. The data handler supports adding SOAP attributes to complex single and n-card types only. Consider the following sample:

<CustInfo City="4" State="5" Street="2" Zip="6">
   <Name xsi:type="xsd:string">1</Name>
   <Street2 xsi:type="xsd:string">3</Street2>
</CustInfo>

Given this business object definition structure (with the attribute level ASI specified to the right of each attribute in Figure 46), the data handler follows these processing steps:

Figure 46. attr_name business object

  1. When traversing a complex attribute, the data handler first generates a corresponding tag for this complex business object attribute. In this example, CustInfo represents the complex business object attribute.
  2. The data handler iterates through the children of the complex business object. Only simple type attributes are considered for attribute creation. If a simple type has an ASI property named attr_name, the data handler writes this simple type as an attribute to the SOAP element. In this example, the element (CustInfo) will have four attributes; Street, City, State and Zip.
  3. The rest of the attributes of the business object are written using standard BODY processing. This means that all relevant ASI will also be evaluated for the business object attributes that do not have attr_name ASI.

The logic for processing multiple cardinality types is identical to that for processing single cardinality types. Specifically, each <item> tag corresponds to each business object instance in the multiple cardinality object, and will be processed using ASI. For example, given this multiple cardinality business object definition structure with corresponding ASI:

Figure 47. attr_name multiple cardinality business object

If the event sent to the data handler had two instances of this multiple cardinality object, the SOAP message created may look like this:

<CustInfo>
   <item City="Armonk" Street="Main Street">
      <Name>IBM</Name>
      <Street2>None</Street2>
   </item>
   <item City="Burlingame" State="Ca" Street="577 Airport Blvd" Zip="94010">
      <Name>Burlingame Labs</Name>
      <Street2>Suite 600</Street2>
   </item>
</CustInfo>

Notice that the item tags are treated as the complex element type. Any attributes in the BO definition will become SOAP attributes of the corresponding item tag.

arrayof processing for simple type arrays

The arrayof ASI property should only be used in the case of SOAP encoded simple type arrays. For example, a serialization such as the following:

<CustomerNames SOAP-ENC:arrayType="xsd:string[4]" xmlns:SOAP-ENC=
"http://schemas.xmlsoap.org/soap/encoding/" xsi:type="SOAP-ENC:Array">
<item xsi:type="xsd:string">value1</item>
<item xsi:type="xsd:string">value2</item>
<item xsi:type="xsd:string">value3</item>
<item xsi:type="xsd:string">value4</item>
</CustomerNames>

would require a business object definition such as that shown inFigure 48 :

Figure 48. arrayof business object

(The business object is shown from the Request level for clarity. )

Note:
Although not shown, the SOAP Config MO's TypeInfo property must be set to true in this example to derive the above SOAP serialization from the business object structure.

Also, the arrayof property can be used to create array items with a name other than item. Using the example above, the <item> tags can be replaced with <name> tags if both the BO attribute name and the "arrayof" asi property value is name. This would be the serialization:

<CustomerNames SOAP-ENC:arrayType="xsd:string[4]" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xsi:type="SOAP-ENC:Array">
<name xsi:type="xsd:string">value1</name>
<name xsi:type="xsd:string">value2</name>
<name xsi:type="xsd:string">value3</name>
<name xsi:type="xsd:string">value4</name>
</CustomerNames>

attr_name and attr_ns processing

You may need to provide a namespace that corresponds to the SOAP attribute created. You do this by specifying the attr_ns ASI property for a simple type. The data handler processes the attr_ns property if and only if attr_name exists in the same attribute's ASI. The following rules are followed with attr_name and attr_ns:

  1. When neither attr_name nor attr_ns exist, the business object attribute is translated to a SOAP element.
  2. When only attr_name is set, the SOAP attribute's namespace defaults to the element's namespace:
    <CustInfo Street="577 Airport"></CustomerInfo>
  3. When only attr_ns is set, the property is ignored and the business object attribute is translated to a SOAP element.
  4. When both attr_name and attr_ns exist, the SOAP attribute is created like the following:
    <CustInfo ns2:Street="577 Airport" xmlns:ns2=
    "AttrNS"></CustomerInfo>

dh_mimetype: calling a data handler

The SOAP data handler can call another data handler to write business objects into any format for which a data handler exists. You do this by adding encoded text to a SOAP message when transferring a SOAP child business object into a SOAP String.

An RNIF document is one of the formats in which a SOAP element's value may be encoded. To make use of this functionality, add an RNIF BO at any level of a SOAP child business object. To signal the SOAP data handler to call another data handler when transforming this RNIF business object to a string, add the dh_mimetype property to the attribute's ASI. The value of the dh_mimetype ASI property must be a legal mimeType specified in the MO_DataHandler_Default meta-object. The mimeType is used to determine which data handler is called to process the business object.

Figure 49 shows a SOAP child business object in which CustomerInfo is a complex child and RNET_Pip3A2PriceAndAvailabilityQuery is an RNIF business object:

Figure 49. RNIF business object with dh_mimetype

The SOAP message created from this business object may look like this:

<CustomerInfo>
<Name>IBM Corporation</Name>
<CustID>95626</CustID>
<RNIFexample
xsi:type="xsd:base64Binary">1AWERYER238W98EYR9238728374871892787ASRJK23423
JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJK234
34JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJK2
4234JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJ
234234JKAWERJ234AWERIJHI423488R4HASFWR234
</RNIFexample>
</CustomerInfo>

Note that the RNIF example element contains an RNIF encoded string that has been base64 binary encoded as its element value. Also, note that elem_name, elem_ns, type_name, type_ns, and xsdtype ASI properties remain relevant for this business object attribute. In this example, the specified elem_name dictates the name of the SOAP element upon message creation.

Note:
If the element value returned by the called data handler is encoded text, the type_name property must be set to base64Binary, the type_ns must correspond to an xsd namespace, and xsdtype must be set to true.
xsd:base64Binary

When you set the type_name and type_ns to resolve to xsd:base64Binary, the SOAP data handler encodes the value from the business object before setting the value for the corresponding element. Using the Apache API, the data handler queries the registry for a base64Binary serializer, serializes the string returned from the called data handler, and sets the element's value.

Schema complexType indicators

The following sections discuss the effects of schema complexType Indicators on business objects. The indicators include:

maxOccurs and minOccurs indicators for simple types

The maxOccurs indicator specifies the maximum number of times an element can occur within a complex type. The minOccurs indicator specifies the minimum number of times an element should occur within a complexType.

Consider this Schema:

<xs:element name="Address" type="Address">
<xs:complexType name="Address">
     <xs:sequence>
        <xs:element name="AddressLine" type="xsd:string" maxOccurs="10"/>
        <xs:element name="SuiteNumber" type="xsd:string" minOccurs="3"
                             maxoccurs="unbounded"/>
        <xs:element name="City" type="xsd:string"/>
     </xs:sequence>
     </xs:complexType>
</xs:element>

The example above indicates that the AddressLine element can occur at most ten times in an Address element, while the SuiteNumber element must occur at least three times. The business object that corresponds to this schema must have an N cardinality wrapper object for each maxoccurs/minoccurs indicator that has the following ASI:

maxOccurs=N;wrapper=true

or

minOccurs=3;wrapper=true;

The wrapper=true ASI indicates that this object is a wrapper, and therefore not explicitly written to the SOAP message. Instead, there must be one child of simple type in this wrapper object. At runtime, for SOAP to business object transformations, the data handler reads the N child objects of the wrapper and creates a corresponding element for each one. When performing business-object-to-SOAP-message transformations, the data handler creates child objects in the N cardinality wrapper for every element it encounters.

The corresponding SOAP business object resembles that shown in Figure 50.

Figure 50. minOccurs and maxOccurs of simple type ASI in a SOAP business object

The SOAP message that corresponds to the business object shown in Figure 50 is as follows:

<Address xsi:type="ns0:Address">
    <AddressLine xsi:type="xsd:string">Line1</AddressLine>
    <AddressLine xsi:type="xsd:string">Line2</AddressLine>
    <SuiteNumber xsi:type="xsd:string">600</SuiteNumber>
    <SuiteNumber xsi:type="xsd:string">650</SuiteNumber>
    <SuiteNumber xsi:type="xsd:string">700</SuiteNumber>
     <City xsi:type="xsd:string">San Francisco</City>
</Address>

Note:
The SOAP data handler processes maxOccurs and minOccurs indicators in the same way, without validating the maximum or minimum occurrences of elements. The data handler simply provides a container structure to hold multiple instances of a particular element with the maxOccurs and minOccurs indicators. This applies to simple and complex types.
maxOccurs and minOccurs indicators for complex types

The <maxOccurs> indicator specifies the maximum number of times an element can occur within a complex type. The <minOccurs> indicator specifies the minimum number of times an element should occur within a complexType. Consider the maxOccurs indicator in the following schema:

<xs:element name="Address" type="Address">
<xs:complexType name="Address">
     <xs:sequence>
     <xs:element name="AddressInfo" type="AddressInfo" maxOccurs="3"/>
     <xs:element name="City" type="xsd:string"/>
  </xs:sequence>
  </xs:complexType>
</xs:element>

<xs:complexType name="AddressInfo">
     <xs:sequence>
     <xs:element name="StreetLine" type="xsd:string"/>
     </xs:sequence>
  </xs:complexType>
</xs:element>

The example above indicates that the AddressInfo complex type element can occur at most three times in an Address element. The corresponding business object for this schema will not have a wrapper object, since the complexType AddressInfo itself can be of N cardinality. The following ASI will be placed at the N cardinality attribute: maxoccurs=3

Figure 51 shows the corresponding SOAP business object.

Figure 51. minOccurs and maxOccurs of complex type ASI in a SOAP business object

The SOAP message that corresponds to the business object shown in Figure 51 is as follows:

<Address xsi:type="ns0:Address">
     <AddressInfo xsi:type="ns0:AddressInfo">
        <StreetLine xsi:type="xsd:string">100 Market St.</ StreetLine>
        <StreetLine xsi:type="xsd:string">Apt 15</ StreetLine>
     </AddressInfo>
  <City xsi:type="xsd:string">San Francisco</City>
</Address>
all indicator

The all indicator specifies by default that the child elements for this complexType can appear in any order and that each child element must occur zero or one times. Consider the following Schema:

<complexType name="Item">
     <all>
        <element name="quantity" type="xsd:int"/>
        <element name="product" type="xsd:string"/>
     </all>
</complexType>

The example above indicates that the elements quantity and product, can occur in any order in the SOAP message. The quantity element may occur first and the product element second, or vice versa.

Figure 52 shows the business object that corresponds to this schema fragment.

Figure 52. all indicator ASI in a SOAP business object

The corresponding SOAP message fragment is as follows:

<Item xsi:type="ns0:Item">
    <quantity xsi:type="xsd:string">12</quantity>
    <product xsi:type="xsd:string">2</product>
</Item>
Handling array content with 'all' content model

The SOAP data handler processes complex-type array content with the 'all' content model as described in this section. In the example, ArrayOfSOAPStruct contains SOAPStruct, which has the 'all' content model.

<complexType name="SOAPStruct">
       <all>
       <element name="varString" type="string" />
       <element name="varInt" type="int" />
       <element name="varFloat" type="float" />
       </all>
</complexType>
<complexType   name ="ArrayOfSOAPStruct'">
  <complexContent>
   <restriction base='SOAP-ENC:Array'>
    <attribute ref='SOAP-ENC:arrayType'
     wsdl:arrayType='typens:SOAPStruct[]'/>
   </restriction>
  </complexContent>
 </complexType>

The SOAP data handler must generate the following SOAP data on serialization:

<?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>
 <ns0:echoStructArray xmlns:ns0="http://soapinterop.org/">
  <inputStructArray SOAP-ENC:arrayType="ns1:SOAPStruct[2]"
           xmlns:ns1="http://soapinterop.org/xsd" xsi:type="SOAP-ENC:Array">
      <item>           
                   <ns1:varFloat xsi:type="xsd:string">1.1</ns1:varFloat>
                   <ns1:varInt xsi:type="xsd:string">1</ns1:varInt>
           <ns1:varString xsi:type="xsd:string">hi</ns1:varString>
      <item>
      <item>
           <ns1:varString xsi:type="xsd:string">hello</ns1:varString>
           <ns1:varInt xsi:type="xsd:string">1</ns1:varInt>
           <ns1:varFloat xsi:type="xsd:string">1.1</ns1:varFloat>
         </item>
     </inputStructArray>
    </ns0:echoStructArray>
  </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

In this example, echoStructArray is the name of the operation, and inputStructArray is the parameter name with type ArrayOfSOAPStruct.

sequence indicator

The sequence indicator specifies that child elements must appear in the order specified in the complexType.

<complexType name="Item">
     <sequence>
        <element name="quantity" type="int"/>
        <element name="product" type="string"/>
     </sequence>
</complexType>

The SOAP data handler does not require special ASI or wrapper objects for this indicator. By default, the data handler reads and writes SOAP elements in the order specified in the business object.

choice indicator

The choice indicator specifies that one and only one of the elements in a complexType can appear in the SOAP message. Consider the following schema:

<complexType name="Item">
    <choice>
        <element name="quantity" type="int"/>
        <element name="product" type="string"/>
    </choice>
</complexType>

The SOAP data handler does not require special ASI or wrapper objects for this indicator. When converting a business object to a SOAP message, the data handler defers to your choice of which elements should appear in the SOAP message. When converting a SOAP message to a business object, the data handler reads the existing element and populates the attribute to which it corresponds.

maxOccurs indicator on sequence, choice, group and all

Model Groups (sequence, choice, group, and all) have minOccurs and maxOccurs attributes. The default value for minOccurs and maxOccurs is one. For the all group, the maxOccurs can take a value of one only. The WSDL ODA and SOAP data handler support all possible values for maxOccurs on sequence, choice and group.

ASI in SOAP-to-business object transformations

The SOAP data handler uses a business object's ASI to read and validate an incoming SOAP message. The following rules apply to ASI validation by the SOAP data handler:

Note:
Unless otherwise stated, all ASI discussed in the following sections is attribute-level ASI

elem_name validation

The following rules apply to validation for simple, cardinality 1 and cardinality n attributes:

  1. When encountering an element while parsing a SOAP message, the data handler first searches all of the ASI at the business object level, attempting to match the element's name against the elem_name value.
  2. If a match is not found, the data handler attempts to match the element's name against each of the attribute names at that business object level.
  3. If neither search succeeds, the data handler fails.

elem_ns validation

The following cases apply to validation for simple, cardinality 1 and cardinality n attributes:

  1. When neither elem_ns ASI nor xmlns from the SOAP message for this element exist, the element is properly validated.
  2. When elem_ns ASI does not exist and the corresponding element from the SOAP message does have an xmlns specified, the data handler defaults the elem_ns to the last elem_ns read from the business object that was in the scope. The data handler compares this value with the xmlns value from the SOAP message. If there is no match, validation fails.
  3. When elem_ns ASI does exist and the corresponding element from the SOAP message does not have xmlns specified, the data handler verifies that the elem_ns specified in ASI matches one of the namespaces in the current scope of the SOAP message. If there is no match, validation fails.

type_name and type_ns validation

The sections below discuss type_name and type_ns validation.

Simple attributes

The following rules apply to type_name and type_ns validation when xsdType is true:

The following rules apply to type_name and type_ns validation when xsdType is false:

Complex attributes (cardinality 1 and n)

The following rules apply to type_name and type_ns validation when xsdType is true:

The following rules apply to type_name and type_ns validation when xsdType is false:

attr_name and attr_ns validation

While reading SOAP message into a business object, each SOAP element is searched for SOAP attributes. If found, these attributes are compared to the attr_name property values from the corresponding BO. For example, consider this SOAP message:

<CustInfo City="4" State="5" Street="2" Zip="6">
   <Name xsi:type="xsd:string">1</Name>
   <Street2 xsi:type="xsd:string">3</Street2>
</CustInfo>

Now consider the business object definition structure (with the attribute level ASI specified to the right of each attribute) shown inFigure 53.

Figure 53. attr_name and attr_ns validation

The data handler would follow these processing steps:

  1. Read the element name CustInfo.
  2. Resolve the business object attribute that corresponds to this element name.
  3. Read the attributes of the SOAP element and attempt to match them against the ASI of the child attributes. In this case, the SOAP message Street matches the business object attribute Street1, City matches the business object attribute City and so on.
  4. The child elements for CustInfo are read and processed in the same manner as the rest of the body.

Note:
attr_ns is not validated.

The data handler loops through the SOAP attributes for a given element. For each attribute encountered, the data handler searches the business object for a corresponding attribute. If found, the business object attribute is populated with the value of the SOAP attribute. If a corresponding business object attribute is not found, the data handler continues to the next SOAP attribute.

Calling a data handler from within the SOAP data handler

The SOAP data handler can read an encoded element value from a SOAP message into a business object using another data handler. For example, an RNIF document may be one of the formats in which a SOAP element value is encoded. To make use of this functionality, an RNIF business object can be added at any level of a SOAP Child business object. To signify to the SOAP data handler that another data handler must be used when transforming this RNIF encoded String to an RNIF business object, you must add the dh_mimetype property to the attribute's ASI. The value of the dh_mimetype ASI should be a legal mimeType specified in the MO_DataHandler_Default business object. The mimeType is used to determine which data handler to use on the String. For example, given the following SOAP message where RNIFExample is the SOAP element that contains an RNIF encoded String:

<CustInfo>
<Name>IBM Corporation</Name>
<CustID>95626</CustID>
<RNIFexample xsi:type="xsd:base64Binary">
1AWERYER238W98EYR9238728374871892787ASRJK234234JKAWER
J234AWERIJHI423488R4HASF1AWERYER238W98EYR923872837487
1892787ASRJK234234JKAWERJ234AWERIJHI423488R4HASF1AWER
YER238W98EYR9238728374871892787ASRJK234234JKAWERJ234A
WERIJHI423488R4HASF1AWERYER238W98EYR92387283748718927
87ASRJK234234JKAWERJ234AWERIJHI423488R4HASFWR234
</RNIFexample>
</CustomerInfo>

The SOAP business object would look like that shown in Figure 54.

Figure 54. RNIFExample business object

Note that the RNIFExample element contains an RNIF encoded String as its element value. Also, note that elem_name, elem_ns, type_name, type_ns and xsdtype ASI properties still remain relevant for this business object attribute.

Note:
If the element value returned by the called data handler is encoded text, the type_name property must be set to base64Binary, the type_ns must correspond to an xsd namespace, and xsdtype must be set to true.

Default business object resolution

For SOAP to business object transformations, the SOAP data handler and web services connector adhere to a special contract of exchanging information to resolve business object names. The connector provides the SOAP data handler with a list of business object names mapped to BodyName and BodyNamespace pairs. In addition, if there is a defaultfault business object set in the TLO, this information is passed to the data handler. Given this information, the SOAP data handler processes using the following steps:

  1. The data handler receives a SOAP message
  2. The data handler determines if this is a SOAP request, response or fault message.
    1. If a SOAP request or response message, the data handler reads the BodyName and BodyNamespace from the first child element of the SOAP-ENV:Body element.
    2. If a SOAP fault message, the data handler reads the BodyName and BodyNamespace from the first child element of the detail element in the fault message. If there is no detail element in the fault message, the data handler uses the defaultfault business object for this transformation
  3. If a defaultfault business object has not already been chosen, the data handler attempts to match the BodyName and BodyNamespace found in step 2 to the pairs found in the list provided by the connector. If a match is made, business object resolution is successful. If no match is made, the data handler fails with a meaningful error message.

Copyright IBM Corporation 1997, 2004. All Rights Reserved.