SOAP DataHandler Business Object Structure:
================================
This section describes the changes made to the SOAP DataHandler busines object for supporting multiple headers in the SOAP message. For a complete set of requirements for the SOAP DataHandler business object, please refer to the Guide to the IBM CrossWorlds Connector for Web Services.

Terminology:
-------------
SOAP Header Container Business Object: CrossWorlds business object that contains information about the headers on a SOAP message. This business object will contain only child business objects. Each child business object represents a header entry on the SOAP message. The SOAP DataHandler Business Object may have an attribute, which is of type SOAP Header Container Business Object. This attribute is also referred to as the SOAPHeader attribute. Such an attribute has special app-specific-info requirements, as described below.

SOAP Header Child Business Object: CrossWorlds business object that represents a single header element on a SOAP message. The Header element is an immediate child of the SOAP-Env:Header element of the SOAP message. All attributes of a Header Container Business Object should be of this type. These business objects may have an actor and a mustUnderstand attribute. These attributes correspond to the actor and mustUnderstand attributes of the SOAP header element.

SOAP DataHandler Busines Object App-specific-info requirements:
---------------------------------------------------------------------

1. SOAPHeader attribute: 
If there is an attribute in the SOAP DataHandler Business Object with the following app-specific-info:

soap_location = SOAPHeader;

the SOAP DataHandler expects this attribute to be a single cardinality child that is a SOAP Header Container Business Object. This attribute is also referred to as a SOAPHeader attribute. If a Business Object contains more than one such attribute, then the SOAP DataHandler will always process the first one and ignore all others. All SOAP DataHandler Business Objects (including fault Business Objects) may have a SOAPHeader attribute. Note that this attribute can have any valid CrossWorlds business object attribute name.

2. Specifying header namespace:
Each attribute of the SOAP Header Container Business Object should be a 1 or n-cardinality child that is a SOAP Header Child Business Object. The SOAP DataHandler will create (or expect) a header element in the SOAP message with the same name as this attribute. The namespace of this header element can be specified as followed using the app-specific-info of this attribute:

elem_ns = Name space URI;

Header Processing
=============
This section describes header processing only. For the processing of body please refer to the Guide to the IBM CrossWorlds Connector for Web Services.

Header Processing for SOAP DataHandler Business Object to SOAP Message Transformation:
-------------------------------------------------------------------------------------------------
All attributes, except the SOAPHeader attribute of the SOAP DataHandler Business Object are processed as described in the body processing. This section describes the processing of the SOAPHeader attribute only.

1. From the CrossWorlds Business Object, the SOAP DataHandler determines the SOAPHeader attribute. Note that this attribute has app-specific-info of "soap_location=SOAPHeader". The SOAP DataHandler will create a SOAPEnv:Header element only if the value of this attribute is not null. Also if there are multiple such attributes, the SOAP DataHandler will consider only the first one. 

2. The SOAP DataHandler expects that the SOAPHeader attribute is a single cardinality child representing a SOAP Header Container Business Object. The DataHandler will process the child attributes of SOAP Header Container Business Object which are of type SOAP Header Child Business Object. 

3.For each attribute of the SOAP Header Container Business Object (SOAPHeader attribute), the DataHandler does the following:

a. If this attribute is NOT a 1 or n cardinality child object, it will be ignored.

b. If the value of this attribute is NULL, it will be ignored. 

c. If this attribute IS a 1 or n cardinality child object, the SOAP DataHandler will create a header element, which will be the immediate child of the SOAP-Env:Header element created in step 1. The name of this header element will be same as the name of this attribute. The name space of this element will be given by the elem_ns app-specific-info of this attribute.

d. If this attribute is a SOAP Header Child Business Object, all of the attributes of this business object will be processed. This attribute may have an actor and a mustUnderstand attribute.

e. If a SOAP Header Child Business Object has a non-null actor attribute, the DataHandler will create an actor attribute in the header element created in c. 

f. If a SOAP Header Child Business Object has a non-null mustUnderstand attribute, the DataHandler will create a mustUnderstand attribute in the header element created in c.

g. All other non-null attributes of the SOAP Header Child Business Object become child elements of this header element. They will be composed in the same manner the child elements of the SOAP-Env:Body element are.

Header Processing for SOAP Message to SOAP DataHandler Business Object transformation:
--------------------------------------------------------------------------------------
The body of the SOAP Message will be processed as described in the "Guide to the IBM CrossWorlds Connector for Web Services." This section describes the processing of a SOAP Header.

1. The SOAP DataHandler processes the body of a SOAP message. Body processing creates a SOAP business object.

2. If the SOAP message has a SOAP Header element, the SOAP DataHandler will expect a SOAPHeader attribute in the SOAP Business Object obtained from body processing. Note as described above, SOAPHeader attribute is the child attribute of the SOAP business object, which has app-specific-info of "soap_location=SOAPHeader". If there is no such attribute, the SOAP DataHandler will throw an error. This attribute should be of type SOAP Header Container Business Object. The SOAP DataHandler will create an instance of this attribute in the SOAP Business Object obtained in step 1.

3. For each immediate child element of the SOAP-Env:Header element, the SOAP DataHandler does the following:

a. The DataHandler expects a child attribute in the SOAP Header Container Business Object. The name of this attribute should be the same as the name of this header element. This attribute should conform to the SOAP Header Child Business Object. If the DataHandler cannot find such an attribute, it throws an error. Additionaly, the namespace of this element should be the same as specified in the elem_ns app-specific-info of this attribute. If it is not the same, the DataHandler throws an error.

b. The DataHandler creates an instance of this SOAP Header Child Business Object, and sets it in the instance of SOAP Header Container Business Object created in step 2.

c. If this header element has an actor attribute, the DataHandler expects an actor attribute to exist in the child business object created above. If it cannot find an actor attribute, it throws an error.

d. If this header element has a mustUnderstand attribute, the DataHandler expects a mustUnderstand attribute to exist in the child business object created above. If it cannot find a mustUnderstand attribute, it throws an error.

e. For each child element of this header element, the DataHandler expects an attribute in the child business object with the same name. These elements will be processed in same way as the child elements of SOAP-Env:Body element.

Web Services Generation Utility:
======================
1. Specifying headerfault
The SOAP specification states that errors pertaining to headers must be returned in headers. These headers will be returned in the SOAP fault message. Message headers are specified in the SOAPHeader attribute of request and response business objects. Likewise, fault headers are specified in the SOAPHeader attribute of fault business objects. Each of the possible headers of request or response business objects, may cause an error. This error will be reported in the headers of the fault message. WSDL documents have a SOAP binding headerfault element that allows you to specify the fault header. The fault header will be used when the headers in a request or response message throw an error. (For more details please refer to SOAP and WSDL Specs).

headerfault app-specific-information allows you to specify header faults for each of your headers. You may specify headerfault app-specific info for each of the attributes of the SOAP Header Container Business Object. It gives the list of attributes in the SOAP Header Container Business Object attribute of the fault business object.

headerfault=attr1, attr2, attr3...

If the utility finds headerfault app-specific info in the SOAP Header Child Business Objects of request or response objects, the utility will create headerfault elements in the WSDL generated for these headers. Note that WSDL allows you to specify multuple headerfaults for each of your request/response headers. Therefore the value of this app-specific-info is a comma delimited list of attributes.

Sample Business Objects:
==================
This section shows sample Business Objects. This section assumes there is a SOAP request business object of type SOAPApp_CustCreateRequest, and there is a corresponding fault business object SOAPApp_CustCreateFault. It is assumed that the SOAP (request) message will be created using SOAPApp_CustCreateRequest. If there is any fault, the DataHandler will convert the fault message into SOAPApp_CustCreateFault. This section does not describe meta-objects.

SOAP Business Object (Request or Response):
-------------------------------------------
The following is SOAP Business Object of type SOAPApp_CustCreateRequest. This section shows all of its attributes and their types. Note the app-specific-info of SOAPHeader attribute (custheader). Also note that this attribute is a SOAP Header Container Business Object of type TransactionHeaderListWithHeaderFault. The child attributes of TransactionHeaderListWithHeaderFault have headerfault app-specific-info. This has been intentionally done to illustrate that the attributes of the SOAP Header Container Business Object, which is in the SOAP Request or Response business objects, may have headerfault elements.

Note that the attribute list specified in the headerfault app-specific-info of the attributes of TransactionHeaderListWithHeaderFault refers to the attributes of the SOAPHeader attribute of the SOAP Fault Business Object. In this example, lets take the app-specific-info for the attribute soaptransaction of TransactionHeaderListWithHeaderFault.

headerfault=transaction,sender;elem_ns=www.mynamespace.com/transactions;

headerfault refers to the transaction and sender attributes of the TrasactionHeaderList business object. Similarly the headerfault app-specific-info of TransactionHeaderListWithHeaderFault.soapsender would refer to TransactionHeaderList.sender and the headerfault app-specific-info of TransactionHeaderListWithHeaderFault.soapreciever would refer to TransactionHeaderList.reciever.

SOAP Business Object (Request or Response)
Name: SOAPApp_CustCreateRequest
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
customerid String
customername String
customeraddress Address
custheader TransactionHeaderListWithHeaderFault soap_location=SOAPHeader

SOAP Header Container Business Object (Request or Response)
Business Object Name: TransactionHeaderListWithHeaderFault
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
soaptransaction TransactionHeaderType headerfault=transaction,sender;elem_ns=www.mynamespace.com/transactions;
soapsender TradingPartnerType headerfault=sender;elem_ns=www.mynamespace.com/tradingpartner;
soapreciever TradingPartnerType headerfault=reciever;elem_ns=www.mynamespace.com/tradingpartner;

SOAP Header Child Business Object:
Business Object Name: TransactionHeaderType
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
actor String
mustUnderstand String
transactionId String
routeNumber String

SOAP Header Child Business Object:
Business Object Name: TradingPartnerType
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
partnerId String
messageType String


SOAP Fault Business Object
-----------------------------
The following is a SOAP Fault Business Object of type SOAPApp_CustCreateFault. Note the app-specific-info of the SOAPHeader attribute. Also note that the type of this attribute has been intentionally set to TransactionHeaderList. All the child attributes of this Header Container Business Object do not have headerfault app-specific-info. This has been intentionally done, to illustrate that attributes of SOAP Header Container Business Object of SOAP fault business objects may not have headerfault elements.

Business Object Name: SOAPApp_CustCreateFault
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
faultcode String
faultstring String
faultactor String
detail CustCreateError
custfaultheader TransactionHeaderList soap_location=SOAPHeader


Header Container Business Object:
The following is a Header Container Business Object of type TransactionHeaderList.

Business Object Name: TransactionHeaderList
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
transaction TransactionHeaderType elem_ns=www.mynamespace.com/transactions;
sender TradingPartnerType elem_ns=www.mynamespace.com/tradingpartner;
reciever TradingPartnerType elem_ns=www.mynamespace.com/tradingpartner;


Header Child Business Object:
The following is a Header Child Business Object of type TransactionHeaderType.

Business Object Name: TransactionHeaderType
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
actor String
mustUnderstand String
transactionId String
routeNumber String

The following is a TradingPartnerType Header Child Business Object.

Business Object Name: TradingPartnerType
Attribute Type App-specific-info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
partnerId String
messageType String