The SOAP data handler performs transformations between SOAP
messages and business objects in the following ways:
- SOAP message to business object processing
- Request-message-to-SOAP-request-business-object data handling
occurs at that stage in event processing when web service clients
make calls to collaborations exposed as web services
- Response-message-to-SOAP-response-business-object data handling
occurs during request processing when a web service returns a SOAP
response message to a collaboration that had invoked it.
Alternatively, fault-message-to-SOAP-business-object data handling
may occur at this phase.
For a detailed description of this processing, see SOAP-body-message-to-business-object processing
later in this section.
- Business object to SOAP message processing
- Business-object-to-SOAP-response-message data handling occurs
during event processing when a response business object is returned
by the collaboration that is exposed as a web service.
Alternatively, fault business object-to-SOAP-fault-message data
handling may occur at this phase.
- Business-object-to-SOAP-request-message data handling occurs at
that phase of request processing when a collaboration makes a
service call to the connector to convert a business object to a
SOAP request message.
For a detailed description of this processing, see Business-object-to-SOAP-message-body processing
later in this section.
This section provides a step-by-step description of the
SOAP-body-message-to-business-object transformation.
- The SOAP data handler receives a SOAP message.
- Using Apache SOAP APIs, the data handler parses the SOAP
message.
- The data handler extracts the components of the SOAP message:
envelope, header, and body.
- Header processing For more, see SOAP-header-message-to-business-object
processing.
- 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- faultcode: Required. String attribute
- faultstring: Required. String attribute
- faultactor: Not required String attribute
- detail: Not required. Child BO
- 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.
This section describes how the data handler converts the header
of a SOAP message into a business object.
- The SOAP data handler processes the body of a SOAP message.
Body processing creates a SOAP business object.
- 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.
- For each immediate child of the SOAP-Env:Header element:
- 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.
- 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.
- 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.
- 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.
- 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.
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
- The SOAP data handler looks for a SOAP ConfigMO that
corresponds to the SOAP business object it is transforming.
- The data handler composes the envelope and header of the SOAP
message.
- 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.
- 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:
- The data handler obtains the BodyName and BodyNS from the SOAP
ConfigMO attributes and then composes the first (parent) element of
the body of the SOAP message. The name of first element is, by
default, the value for the BodyName. In this document, it is also
referred to as the body element. The namespace of the body element
is, by default, the value determined for BodyNS. If the Style
attribute of the SOAP ConfigMO is set to document, this
step (creating the first body element) is skipped.
- The data handler then reads the attributes of the business
object and processes them by type. The processing for each type of
attribute is described below.
- Simple attributes If the attribute is of type simple,
the data handler creates a child element from the body element,
with the same name as the attribute (unless otherwise specified by
special application-specific information). The data handler sets
the value of this element to the value of the attribute in the
business object.
- Cardinality 1 child business object attributes
If the attribute is a single cardinality child business object,
the data handler creates a child element of the body element. This
is referred to as a child business object element. The name of the
child element created is the same as that of the attribute (unless
otherwise specified by special ASI properties). The data handler
then traverses the attributes of the child business object,
creating the child elements for the attributes in the same way it
processes the attributes of the incoming business object. However,
the child elements are made children not of the body element but of
the child business object element
- Cardinality n child business object attributes If an
attribute is a cardinality n child business object, the data
handler creates a SOAP array. Each attribute is handled the same
way that a single cardinality child business object is
handled.
- Composing fault The following section walks through the
process by which the data handler composes a fault message.
- 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.
- 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.
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".
- 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.
- 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.
- For each attribute of the SOAP Header Container business
object, the data handler does the following:
- Checks the cardinality: if this attribute is NOT a 1
or n cardinality child object, it is ignored.
- Checks the value: if the value of this attribute is NULL, it
will be ignored.
- 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.
- 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.
- 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.
- 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.
- 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.
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.
