October 25, 2020
Hot Topics:

User Defined Exceptions: Improve Error Handling in Web Services

  • By Ayyappan Gandhirajan
  • Send Email »
  • More Articles »

Exception handling is an important aspect in any software application development. An exception is an event that occurs during the execution of a program that disrupts the normal flow of instructions. When the exception occurs in a Web Service, it will be propagated to the client as a SOAP fault. This article will help you understand different types of exceptions that could be thrown inside the Web Service and how user defined exceptions can improve error handling in your Web Service.

Different Types of Exceptions

Exceptions could be thrown inside a Web Service for various reasons. The possible types of exceptions that could be thrown are RuntimeException, RemoteException, SOAPFaultException and User Defined Exception.

The Web Service developer might try throwing a RuntimeException such as NullPointerException or ArrayIndexOutOfBoundsException inside the Web Service. But, throwing RuntimeException inside the Web Service is considered to be a bad exercise because RuntimeException will always be converted into RemoteException at the client side. While the client is waiting to catch the RuntimeException after invoking a Web Service, he will get only the RemoteException instead of RuntimeException. Eventually, he cannot perform proper error handling for RuntimeException.

The problem with throwing RemoteException is that the different client side libraries will interpret this exception in different ways. It is not portable.

The appropriate exception that the Web Service application could throw is SOAPFaultException. The SOAPFaultException contains four parts: faultcode, faultstring, actor, and detail. This exception can give you the complete information about the error condition. The faultcode might tell you whether the error has happened because of the Server, Client, or something else. For example, when a client doesn't provide security information such as username and password in the HTTP/SOAP header but the service mandates them, the pre-processing logic in the service implementation might obviously throw an authentication exception. This kind of error is considered to be a Client error. The faultstring contains the corresponding description of the error condition that has happened. This string message is human readable and the developer can easily debug the problem with the help of it. The detail element contains the actual exception message and its complete stack trace. Actually, the detail element is an instance of the javax.xml.soap.Detail class and can be created by using the javax.xml.soap.SOAPFactory.createDetail() API.

User-Defined Exceptions

Although SOAPFaultException gives necessary information that is needed to debug the problem, the Web Service client might want to do something more with a fault message that he had received. The one thing that he might want to do is to have a configurable and dynamic text description of the error that occurred. The other thing could be to have the internationalization support for the error messages. By providing text description in languages other than English, he could try addressing needs of all set of people. The list may grow more and more.

To achieve the previously stated goals, a user-defined exception with some specific format could be thrown in the service. Based on the exception that the client has received, he can decide what to do with fault message. The user-defined exception thrown inside the Web Service is directly mapped into wsdl:fault element in the Web Services Description Language (WSDL) of the Web Service. You could see the fault element as one of the child elements of operation element of the portType. The other two child elements of operation are input and output. The fault element, an optional field in the operation element, defines the abstract format of the error message that might be thrown by the Web Service. The wsdl:message element pertaining to WSDL:fault can contain only one message part, and the message part could be either a complexType or simple XMLType.

I propose here how a user-defined exception, MyCustomException, could be defined to better handle error messages. The MyCustomException contains an appropriate fault message that is as defined in the WSDL definition. The fault message contains the following three parts:

  • Error Code, containing a five-letter identifier plus a three-digit identifier

    For example, GENEX001 could mean a generic error, whereas AUTEX001 could mean an authentication error.

  • Text describing the fault, including substitution variables (mentioned as {0}, {1}, and so forth)

    For example, the corresponding text description for Error Code GENEX001 will be something like "Number that you have entered is {0}."

  • A list of values corresponding to the substitution variables defined in the above text.

    For example, for the above case, the variable list will contain only one value (say 1) because the text description above contains only one substitution variable.

    After processing the text using relevant logic, the final text description would be "Number that you have entered is 1."

With the above approach:

  • Faults can be identified, using the error code, without the need for applications or people to parse or understand the fault text (which may be in a unknown language).
  • Text description can be defined in many languages, and corresponding variables can be placed accordingly in a language-independent manner.
  • Internationalization support can be offered by the Services by providing alternate language forms of fault messages automatically by replacing the text description portion only.

Sample: Service, Exception Class, WSDL, and Client

In this section, you will see a sample for service, exception, WSDL, and client. These samples will use Weblogic implementation.

Service Implementation

This service takes two inputs: int number and String message. If the number is 1, SOAPFaultException will be thrown. If the number is 2, MyCustomException will be thrown; otherwise, the method will return successfully.

package WS.exception;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.Detail;

public class ExceptionService{
   public String echo(int number, String message)
          throws MyCustomException{
      System.out.println("Number: "+number+", Message: " + message);
         case 2:
            throw new MyCustomException(
            "Number that you have entered is {0}",
            new String[]{String.valueOf(number)}
         case 1:
            Detail detail = null;
               detail = SOAPFactory.newInstance().createDetail();
               //add error message here
                  "Choice 1 means SOAPFaultException");
            }catch(SOAPException ex){
               throw new MyCustomException(
                  "Error while creating detail element",
                  new String(){});

            throw new javax.xml.rpc.soap.SOAPFaultException(
               new javax.xml.namespace.QName("env.Server"),
               "Number that you have entered is "+number,
               "NO ACTOR",

      return "SUCCESS";

Page 1 of 3

This article was originally published on March 29, 2005

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date