SOAP data handler processing

The SOAP data handler performs transformations between SOAP messages and business objects in the following ways:

SOAP-body-message-to-business-object processing

This section provides a step-by-step description of the SOAP-body-message-to-business-object transformation.

  1. The SOAP data handler receives a SOAP message.
  2. Using Apache SOAP APIs, the data handler parses the SOAP message.
  3. The data handler extracts the components of the SOAP message: envelope, header, and body.
  4. Header processing For more, see SOAP-header-message-to-business-object processing.
  5. Body processing The data handler reads the first element of the SOAP body to determine if it carries a fault or data. If the body content is not a fault, the data handler does the following:
    1. Performs business object resolution to determine which business object will be used in the transformation. If you have configured a custom name handler, the default business object resolution discussed below may not apply. For more on specifying a pluggable name handler, see Specifying a pluggable name handler.
    2. The data handler also resolves the SOAP Config MO (a child of the SOAP business object that the data handler is creating) that will be used for the transformation. If an instance of the SOAP Config MO does not exist, the data handler creates an instance and reads its default values. From the ConfigMO attribute values, the data handler reads the business object verb. The data handler instantiates the SOAP business object and sets the verb accordingly. This is the business object into which the data handler will attempt to write the SOAP message.
    3. The data handler continues parsing the SOAP message one element at a time. For rpc, the data handler expects the first element to be the parent.
    4. The data handler expects that the attributes of the business object (or its application-specific information: for further information, see ASI in business-object-to-SOAP-message transformations) should have the same name as the child elements. If the attribute is not found in the business object, the data handler throws an exception. Child elements may be of simple type or they may be of complex type. Complex elements are those which have child elements.
    5. Simple element If a child element is a simple element, by default, the data handler expects a business object attribute with the same name (or ASI) as that of a simple element. The data handler reads the value of the simple element and sets it in the business object.
    6. Complex element If a child element is of complex type, the data handler expects the business object to have an attribute with the same name (or ASI) and of type child business object. This attribute may be of single cardinality or of multiple-cardinality depending on if there will be a complex SOAP element or SOAP array. Next the data handler instantiates the child business object (by default, the type of the attribute gives the name of the child business object) and reads all the child elements of this complex element, setting their values in the child business object. The data handler sets this child business object into the parent business object attribute after verifying the cardinality of this attribute. If the attribute is cardinality n, the data handler appends this business object to the container. The complex element can have either simple or complex child elements. These are also handled in the same way: if it is simple element, the data handler sets the value in the child BO; if it is a complex element, the data handler instantiates a child business object.
  6. Fault processing The data handler reads the name of the first element of the SOAP body to determine if it is a fault. If the name of the first element is Fault, the data handler concludes that this is a fault message. Fault business object resolution occurs to determine into which business object this fault message should be transformed. The data handler then follows the same processing as that for body processing. The data handler expects that the business object specified in the child business object should have the following attributes:
    1. faultcode: Required. String attribute
    2. faultstring: Required. String attribute
    3. faultactor: Not required String attribute
    4. detail: Not required. Child BO
  7. If fault processing fails for any reason, the exception thrown will contain the text from the faultcode, faultstring and faultactor elements in the SOAP fault message

Note:
According to SOAP specifications for fault messages, faultcode, faultstring, and faultactor are simple elements whereas detail is a complex element (an element with child elements). In addition, faultcode, faultstring, faultactor, and detail belong to the SOAP envelope namespace, whereas detail child elements may belong to user-defined namespaces.

SOAP-header-message-to-business-object processing

This section describes how the data handler converts the header of a SOAP message into a business object.

  1. The SOAP data handler 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 data handler expects a SOAP header attribute in the business object obtained from body processing. The SOAPHeader attribute is the child attribute of a business object and has soap_location=SOAPHeader as its application-specific information. If there is no such attribute, the SOAP data handler throws an error. The SOAPHeader attribute must be of type SOAP Header Container business object. The SOAP data handler creates an instance of this attribute in the SOAP business object obtained in step 1.
  3. For each immediate child of the SOAP-Env:Header element:
    1. The data handler expects a child attribute in the SOAP Header Container Business Object. The name of this attribute must be the same as that of the header element and conform to the SOAP Header Child business object. If the data handler cannot find such an attribute, it throws an error. Additionally, the namespace of this element should be the same as specified in the elem_ns application-specific information of this attribute. If it is not the same, the data handler throws an error.
    2. The data handler creates an instance of the SOAP Header Child business object and places it in the instance of SOAP Header Container business object created in step 2.
    3. If this header element has an actor attribute, the data handler expects an actor attribute to exist in the child business object created above. If it cannot find an actor attribute, the data handler throws an error.
      Note:
      If you want to add an actor attribute, see Specifying SOAP attributes.
    4. If this header element has a mustUnderstand attribute, the data handler expects a mustUnderstand attribute to exist in the child business object created above. If it cannot find a mustUnderstand attribute, the data handler throws an error.
      Note:
      If you want to add a mustUnderstand attribute, see Specifying SOAP attributes.
    5. For each child element of this header element, the data handler 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.

Business-object-to-SOAP-message-body processing

The following is a step-by-step description of the business-object-to SOAP-body-message transformation. For special cases involving application-specific-information, see ASI in business-object-to-SOAP-message transformations

  1. The SOAP data handler looks for a SOAP ConfigMO that corresponds to the SOAP business object it is transforming.
  2. The data handler composes the envelope and header of the SOAP message.
  3. The data handler resolves the SOAP ConfigMO. If an instance of the SOAP ConfigMO does not exist, the data handler will create an instance and read from the default values. By default, the data handler reads the value of the BodyName attribute in the SOAP ConfigMO to determine whether it is processing a fault business object. If it is set to soap:fault the business object is considered a SOAP fault business object. If it is not a fault business object, the data handler performs the processing described under composing body below, else that described under composing fault.
  4. Composing body The following steps detail the processing performed by the data handler to compose the body of the SOAP message from a business object:
  5. Composing fault The following section walks through the process by which the data handler composes a fault message.
  6. CxIgnore processing If the data handler finds out that the value of an attribute is set to CxIgnore, the data handler does not create an element for this attribute.
  7. CxBlank processing If the data handler determines that the value of an attribute is set to CxBlank, the data handler creates an element for this attribute but does not set its value.

Business-object-to-SOAP-message-header processing

This section describes the processing of the SOAP header attribute only. All other attributes are processed as described in "Business-object-to-SOAP-message-body processing".

  1. From the business object, the SOAP data handler obtains the SOAPHeader attribute. This attribute has soap_location=SOAPHeader as its application-specific information. The SOAP data handler creates a SOAP-Env:Header element if and only if the value of this attribute is not null. If a business object contains more than one SOAPHeader attribute, the first one is processed and the rest are treated as part of the body.
  2. The SOAP data handler expects that the SOAPHeader attribute is a single cardinality child representing a SOAP Header Container business object. The data handler processes the child attributes of the SOAP Header Container business object that are of type SOAP Header Child business object.
  3. For each attribute of the SOAP Header Container business object, the data handler does the following:
    1. Checks the cardinality: if this attribute is NOT a 1 or n cardinality child object, it is ignored.
    2. Checks the value: if the value of this attribute is NULL, it will be ignored.
    3. If the attribute is a 1 or n cardinality child object, the SOAP data handler creates a header element that is the immediate child of the SOAP-Env:Header element created in step 1. The name of this header element is same as that of the attribute. The namespace of this element is given by the elem_ns application-specific information of this attribute.
    4. If the attribute is a SOAP Header Child business object, all of the attributes of this business object are processed. This attribute may have an actor and a mustUnderstand attribute.
      Note:
      If you want to add a mustUnderstand or actor attribute, see Specifying SOAP attributes.
    5. If a SOAP Header Child business object has a non-null actor attribute, the data handler creates an actor attribute in the header element that was created in step c.
    6. If a SOAP Header Child business object has a non-null mustUnderstand attribute, the data handler will create a mustUnderstand attribute in the header element created in step c.
    7. All other non-null attributes of the SOAP Header Child business object become child elements of this header element. They are composed in the same manner as the child elements of the SOAP-Env:Body element.

Header fault processing

The SOAP specification states that errors pertaining to headers must be returned in headers. These headers are returned in the SOAP fault message. Just as message headers are specified in the SOAPHeader attribute of request and response business objects, 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. Such errors are reported in the headers of the fault message.

WSDL documents have a SOAP binding header fault element that allows you to specify the fault header. For more information, see the SOAP and WSDL specifications listed in Chapter 1.

The application-specific information of headerfault allows you to specify header faults for each of your headers. You may specify headerfault application-specific information for each of the attributes of the SOAP Header Container business object. The list of attributes in the SOAP Header Container business object for the fault business object is as follows:

headerfault=attr1, attr2, attr3...
 

If the WSDL Configuration Wizard finds headerfault application-specific information in the SOAP Header Child business objects of request or response objects, the utility creates headerfault elements in the WSDL generated for these headers. Note that WSDL allows you to specify multiple header faults for each of your request (input) and response (output) headers. Therefore the value of this application-specific information is a comma-delimited list of attributes.

Copyright IBM Corp. 1997, 2003