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

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

To page 1To page 2To page 3To page 4To page 5To page 6current page
[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="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:

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


To page 1To page 2To page 3To page 4To page 5To page 6current page
[previous]

Created: November 12, 2001
Revised: November 12, 2001


URL: http://webreference.com/authoring/languages/xml/webservices/chap3/1/7.html