WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (7/7)

[previous]

Professional XML Web Services

faultstring element

If the 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.

faultactor element

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 faultactor element is a placeholder for that type of information. The faultactor element contains a URI that identifies the endpoint where the fault originated.

The 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.

detail element

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 the 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 detail element 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="https://schemas.xmlsoap.org/soap/envelope/" 
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client.MissingParameter</faultcode>
         <faultstring>A parameter was missing</faultstring>
         <faultactor>https://www.wrox.com/heroes/endpoint.asp</faultactor>
         <detail>
            <w:error xmlns:w="https://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 MustUnderstand must 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.

Body-Conscious

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 Envelope, Header, Body, and Fault elements, we can assemble a SOAP message to accomplish what we need. Other than the 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.]