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.
