SOAP data handler processing
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.
SOAP-body-message-to-business-object processing
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.
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.
- 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.
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
- 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.
- The data handler expects the following attributes in the
business object:
- faultcode: Required, String attribute
- faultstring: Required, String attribute
- faultactor: Not required. String attribute
- detail: Not required. Child BO attribute.
If any required attributes are missing, the data handler errors
out.
- The data handler creates an element for faultcode. It sets
the value given by the faultcode attribute of the business object.
- The data handler creates an element for faultstring. It
sets the value given by the faultstring attribute of the business
object.
- The data handler creates the faultactor. It sets the value
given by the faultactor attribute of the business object.
- If the detail attribute is present in the business object,
the attribute should be of child business object type. Otherwise
the data handler errors out. It handles the attributes of each detail
business object as highlighted in the section on Composing body above.
- 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.
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.
- 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.
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.
