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 to create the array for this element |
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. |
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.
The examples discussed in this section assume that the attribute name is OrderId and the SOAP element namespace prefix ns0.
<OrderId>1</OrderId>
elem_name=CustOrderId <CustOrderId>2</CustOrderId>
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>
elem_name=CustOrderId;elem_ns=CustOrderIdNamespace <ns2:CustOrderId xmlns:ns2="CustOrderIdNamespace">1</ns2:OrderId>
For the examples in this section, the attribute name is OrderId, the SOAP element namespace prefix is ns0, and the attribute type is String.
<OrderId xsi:type="xsd:string">1</OrderId>
type_name=CustString <OrderId xsi:type="ns0:CustString">2</OrderId>
type_ns=CustStringNamespace
<OrderId xmlns:ns2="CustStringNamespace" xsi:type=
"ns2:String">3</OrderId>
type_name=CustString;type_ns=CustStringNamespace
<OrderId xmlns:ns2="CustStringNamespace" xsi:type=
"ns2:CustString">1</OrderId>
For the examples in this section, the attribute name is OrderStaus, the SOAP element namespace prefix is ns0, and the attribute type is OrderStatus.
<OrderStatus xsi:type="ns0:OrderStatus">1</OrderStatus>
type_name=CustOrderStatus <OrderStatus xsi:type="ns0:CustOrderStatus">1</OrderStatus>
type_ns=CustTypeNS
<OrderStatus xsi:type="ns2:SOAP_OrderStatusLine
" xmlns:ns2="CustTypeNS">1</OrderStatus>
type_name=CustOrderStatus;type_ns=CustTypeNS <OrderStatus xsi:type="ns2:CustOrderStatus" xmlns:ns2="CustTypeNS">1</OrderStatus>
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.
<MultiLines SOAP-ENC:arrayType="ns0:OrderStatus[2]" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="SOAP-ENC:Array">
type_name=CustOrderStatus <MultiLines SOAP-ENC:arrayType="ns0:CustOrderStatus[2]" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="SOAP-ENC:Array">
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">
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">
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.
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
The faultcode, faultactor, faultstring, and detail elements adhere to the following rules:
You can use all ASI properties (see Table 45) at the header child object level and below.
This is not supported. A business object attribute must be a complex (1 or n cardinality) type for SOAP attributes to be created.
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 45), the data handler follows these processing steps:
Figure 45.
attr_name business object
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 46. 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.
You use the arrayof ASI property to assign SOAP attributes to the array element itself (not at the child tag). You add the arrayof property to the ASI of a single cardinality complex type. The value of the arrayof property must be the name of the multiple cardinality child that the SOAP message will represent. When the SOAP message is created, the multiple cardinality child represents the child tags of the array.
A business object definition with an arrayof element and corresponding ASI are shown inFigure 47
Figure 47.
arrayof business object
If the event sent to the data handler had two instances of this cardinality n object, the SOAP message created may look like the following:
<Customer ID="12"> <CustInfo City="4" State="5" Street="2" Zip="6"> <Name>1</Name> <Street2>3</Street2> </CustInfo> <CustInfo City="10" State="11" Street="8" Zip="12"> <Name>7</Name> <Street2>9</Street2> </CustInfo> </Customer>
Notice that the arrayof property can be used to create array items with a name other than item. In this example, the item tag is replaced with CustInfo tags. This element name is derived from the name of the business object attribute that the arrayof ASI property points to.
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:
<CustInfo Street="577 Airport"></CustomerInfo>
<CustInfo ns2:Street="577 Airport" xmlns:ns2=
"AttrNS"></CustomerInfo>
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 48 shows a SOAP child business object in which CustomerInfo is a complex child and RNET_Pip3A2PriceAndAvailabilityQuery is an RNIF business object:
Figure 48.
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.
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.
The following sections discuss the effects of schema complexType Indicators on business objects. The indicators include:
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 49.
Figure 49.
minOccurs and maxOccurs of simple type ASI in a SOAP business
object
The SOAP message that corresponds to the business object shown in Figure 49 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>
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 50 shows the corresponding SOAP business object.
Figure 50.
minOccurs and maxOccurs of complex 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"> <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>
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 51 shows the business object that corresponds to this schema fragment.
Figure 51.
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>
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.
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.
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:
The following rules apply to validation for simple, cardinality 1 and cardinality n attributes:
The following cases apply to validation for simple, cardinality 1 and cardinality n attributes:
The sections below discuss type_name and type_ns validation.
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:
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:
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 52.
Figure 52.
attr_name and attr_ns validation
The data handler would follow these processing steps:
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.
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 53.
Figure 53.
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.
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: