WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (7/7)
Professional XML Web Services
faultcode element contains the fault information that is meant for
the machine, then the
faultstring element value is what is meant for the user. The
faultstring element contains a string value that briefly describes the fault that
occurred in a way that would make sense if it were displayed to the user in an error dialog. That
is not to suggest that it could not be technical in nature.
It is often just as important to know where the error occurred as it is to know what error
occurred. This is especially true in systems that involve SOAP intermediaries. If a message must pass
through a dozen endpoints before it can reach its final destination for payload processing, the developer
needs to know at what point on the message routing chain an error occurred. The
element is a placeholder for that type of information. The
faultactor element contains a
URI that identifies the endpoint where the fault originated.
faultactor element is only mandatory for intermediaries. If a fault
occurs at an intermediary, then that fault must have a
faultactor element. If the fault
occurs at the final destination, then the endpoint is not required to populate that value (although it
may choose to do so, and it would probably be the nice thing to do for developers who are using our
endpoints). This means that a fault with no
faultactor element can be assumed to have
originated from the final endpoint.
It is possible to provide descriptive error information with just the three elements above,
but additional information would be helpful, if not necessary. For instance, we might want to include in
Fault element the module and source code line of the error while still debugging the
application. In this case, the additional error information can be included as
entries, as seen in the example below.
The specification allows us to define any
detail element entries we choose to,
but it does define one case in which the endpoint returning the
Fault element must return
information in the detail entries: when an error occurs because the server could not process the message
correctly. This is an important requirement, especially in the development of SOAP, because it helps to
debug problems that arise from poorly formed messages. This example shows a SOAP message that might have
resulted from such a message:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap /encoding/"> <soap:Body> <soap:Fault> <faultcode>soap:Client.MissingParameter</faultcode> <faultstring>A parameter was missing</faultstring> <faultactor>http://www.wrox.com/heroes/endpoint.asp</faultactor> <detail> <w:error xmlns:w="http://www.wrox.com/"> <code>178</code> <desc>The codename parameter was missing.</desc> </w:error> </detail> </soap:Fault> </soap:Body> </soap:Envelope>
Endpoint Behavior Revisited
Now that we know more about the structure of a SOAP message, let's consider what is really involved in the three steps of message processing:
Examine the SOAP message to see if it contains any information addressed to this endpoint. Examine the header for entries addressed to this endpoint, either by position (next or last endpoint) or by URI. If this endpoint is the last, look for the body as well.
Examine the header entries targeted at this endpoint. If any are marked with
mustUnderstand="1"and are not recognized by the endpoint, a fault code of
MustUnderstandmust be returned.
If this endpoint is an intermediary, then remove the processed header entries before sending the message to the next endpoint. This does not apply to the body, since only the last endpoint can process that.
These steps, and other requirements of SOAP, will be transparent to most developers. The various SOAP tools and implementations will take into account these requirements when generating endpoints. Part of the beauty of SOAP, however, is the minimal requirements for endpoints. If our application meets these three, it is a valid SOAP endpoint.
The elements that make up the SOAP message structure provide a framework for a message.
Working with those elements, we know where to put our data, where to extend the message, and how to
report errors, among other things. Using the
Fault elements, we can assemble a SOAP message to accomplish what we need. Other
Fault element, which appears inside the body, we have not discussed the actual payload
of the message. The rest of the chapter deals with specific uses for the body, how we can represent
data in the body, and what XML we can place in the body. [To be continued in part 2. - Ed.]
Created: November 12, 2001
Revised: November 12, 2001