Web Service Exceptions

Overview

Exception handling within web services can be a very complicated task, depending on the platform you are using. Some platforms hide the internal implementation of web services. .NET is such an example. Many of the lower-level errors are trapped in the .NET framework and handled gracefully. Other platforms which reveal the actual implementation also reveal lower-level errors more plainly.

So as not to gloss over any of the lower-level details, we will discuss the full range of errors and exceptions below.

Protocol Errors

Fundamentally, web services are not much more than sockets conveying specific information. A web service request and response involves these parts:

1. Client opens a socket to the server
2. Client formats an XML document
3. Client sends the XML content over the socket
4. Server receives the XML content over the socket
5. Server parses the content
6. Server formats XML response content
7. Server sends the response XML content over the socket
8. Client receives the XML response content over the socket
9. Client parses the XML response content

Since the basis of this involves sockets, a wide range of socket errors can occur, all of which prevent successful web service use, all of which must be handled by client programmers.

Examples of these kinds of errors include, but are not limited to:

• Wrong URL endpoint
• SSL errors
• Wrong host name
• Wrong port number
• Certificate errors
• Socket timeout
• Socket creation failure

Your specific platform will dictate how these errors are revealed to the client application, and dictates somewhat how they are to be handled. In some cases, the error is revealed as a return code from a socket function. In other cases the error is revealed through the response buffer, which may or may not contain XML! As a client programmer you are responsible for identifying your particular platform's behavior.

Web Service Engine Errors

To review, web services are not much more than sockets conveying specific information. A web service request and response involves these parts:

1. Client opens a socket to the server
2. Client formats an XML document
3. Client sends the XML content over the socket
4. Server recieves the XML content over the sockedt
5. Server parses the content
6. Server formats XML response content
7. Server sends the response XML content over the socket
8. Client recieves the XML response content over the socket
9. Client parses the XML response content

Platform-specific code on both the client and server sides must both format and parse the XML requests and responses. XML construction and parsing is itself a very detailed operation involving the potential for may problems. The server side adds additional "web service engine" complexity in order to determine which application must be invoked to handle each web service request.

Given this, a wide range of XML parser and web service engine errors can occur. These include, but are not limited to:

• XML is not formatted properly
• Missing required XML content
• XML buffer overflow
• Requested web service not defined

Most of the time, the error is conveyed within the XML response itself. How your particular platform handles errors like this is dependent on the platform, and is the responsibility of the client programmer to understand the platform's behavior. An example of how the XML response will appear is shown below:

<soapenv:Body>
   <soapenv:Fault>
      <faultcode xmlns:p55="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         p55:FailedAuthentication
      </faultcode>
      <faultstring>
         <![CDATA[com.ibm.wsspi.wssecurity.SoapSecurityException: WSEC6521E: Login failed.
         The exception is: javax.security.auth.login.LoginException: WSEC6690E: Failed to
         check username [QUALCOMM@CUSTOMERU] and password in the UserRegsitry:
         UserRegistryProcessor.checkRegistry()=false]]>
      </faultstring>
      <detail encodingStyle=""/>
   </soapenv:Fault>
</soapenv:Body>

Note that errors such as the one above are generated within the web service engine on the server side, and do not involve the actual web service application at all. For example, had the above error been generated in result to a specific method, then the code for that method had not yet been invoked when the error was generated and returned!

Application Specific Errors

A very wide range of error conditions may arise from both socket issues as well as XML and web service engine issues. These are discussed in other topics in this section.

If no socket errors, XML errors, or web service engine errors arise, application-specific errors are also possible. An application-specific error assumes that the web service request was transmitted successfully over the socket, and has made it through the XML parser and the web service engine on the server side. The application code has received the web service request and begun to act on the request.

Application-specific errors are by far the most numerous, because they are solely dependent on the application programmer. Each individual web service may return any number of application-specific errors to the client.

As a generic example, consider a "Update Report" web service, which needs both the current Id, and new information to update in order to process the request. Application-specific errors can vary widely, including:

• Report Not Found
• Missing Required Information

<SOAP-ENV:Body>
  <SOAP-ENV:Fault>
    <faultcode>SOAP-ENV:Client</faultcode>
    <faultstring xml:lang="en">009: Group was not found.</faultstring>
  </SOAP-ENV:Fault>
</SOAP-ENV:Body>