Tip: Make SOAP and Web servers cohabit peacefully

When servers think Web services means Web

SOAP's strength is that it builds on the familiar and widely deployed Web infrastructure. That can also be a weakness because Web servers can make assumptions about Web services that are simply not true. In this installment, Benoît discusses some issues with error handling in Web services.


Benoit Marchal (bmarchal@pineapplesoft.com), Consultant, Pineapplesoft

Photo of Benoit MarchalBenoît Marchal is a Belgian consultant. He is the author of XML by Example, Second Edition and other XML books. He works mostly on XML, Java technology, and e-commerce. For more on this topic, see www.marchal.com. You can contact him at bmarchal@pineapplesoft.com.

19 February 2004

Also available in Japanese

A couple of years ago, I stepped up on the developerWorks Soapbox to express my interest in what was then a nascent protocol, SOAP. My main argument was that you have to love SOAP because it adds useful services to the familiar Web infrastructure.

Now SOAP is a formal W3C Recommendation and I have gained real-world experience with it. For the most part, this experience has validated my initial impression that building on the Web infrastructure is good. The only issue is that the Web is not yet aware of SOAP. This tip shows some of the pitfalls that you will want to avoid when working with SOAP.

No humans here

SOAP specifies that a server should return a SOAP fault when it encounters an error. However servers were designed for browsers, misconfigurations, and network problems, and are more likely to return an HTTP error than a SOAP fault.

You might be thinking Who cares? I'll just configure the servers properly. And yet, if my personal experience is any guide, you should care. For those projects that I worked on during 2001-2002 (that is, stable projects), 80% of the support requests are infrastructure problems.

Most problems can be traced to Internet connections and proxies at the user site. At times, it seems that proxies, NAT (Network Address Translation), DNS (Domain Name Server), and firewalls conspire against Web services. A local network administrator could change a parameter and thus make the service inaccessible.

Faced with a network error, most Web service clients report unintelligible gibberish -- perhaps an exception trace. When a user encounters an exception trace, he will call you, not his network administrator.

To make things worse, you are unlikely to encounter the problem during development, simply because the development server is often located on your local network.

Let them know

If I learned only one lesson while building Web services over the last two years, it is to issue meaningful messages for network errors.

Sadly, JAX-RPC does not help. In fact, JAX-RPC does a very poor job at reporting any error; the SOAPException exception does not even have methods for returning the SOAP fault code, string, or details. Until this is fixed, your best hope is to go through the chain of exceptions until you reach a more meaningful description of the error.

Does Apache help?

Exception chaining

Exception chaining was introduced in JDK 1.4. It defines methods to retrieve information on the root cause of an error.

Apache Axis, one of the most popular SOAP libraries, sets a proprietary AxisFault exception in the Java exception chain for most network errors. This exception allows you to retrieve useful diagnostic information, including the fault code and string.

When the library encounters an HTTP error that results from proxy or server misconfiguration, it sets the fault code to {http://xml.apache.org/axis/}HTTP. This code is specific to Axis (as the namespace URI indicates), but it's better than nothing. Axis 1.2 (in alpha at the time of this writing) goes one step further and returns the HTTP error code in the fault details.

When the library encounters an HTTP error that results from NAT or DNS misconfiguration, Axis sets the fault code to Server.userException. While the Server class is part of the SOAP standard, userException is an extension subcode.

Listing 1 shows sample code that interprets a SOAPException exception as returned by Axis and does a reasonable job of printing meaningful error messages. Listing 1 is specific to Axis (it has been tested with Axis 1.1 and 1.2 alpha) but, again, until error reporting is improved in JAX-RPC you will have to use library-specific code for this.

Listing 1. Reporting network errors
public void printSOAPException(SOAPException x)
 Throwable cause = x.getCause();
 if(cause != null && cause instanceof AxisFault)
 else if(cause != null)
                     + " exception chained: "
                     + x.getMessage());
   System.out.println("SOAP exception: " + x.getMessage());

public void printAxisFault(AxisFault x)
 // tested with Axis 1.1 & Axis 1.2 alpha
 if(x.getFaultCode().equals(new QName("http://xml.apache.org/axis/","HTTP")))
   Element e =
        new QName("http://xml.apache.org/axis/","HttpErrorCode"));
   if(null != e)
      String httpErrorCode = e.getFirstChild().getNodeValue().trim();
         System.out.println("Proxy password incorrect");
      else if(httpErrorCode.equals("502") || httpErrorCode.equals("504"))
         System.out.println("Proxy cannot find the server");
      else if(httpErrorCode.equals("500"))
         System.out.println("Proxy or server unavailable");
      else if(httpErrorCode.equals("404"))
         System.out.println("No Web service (404 File Not Found)");
      System.out.println("Network error: " + x.getFaultString());
 else if(x.getFaultCode().equals(
          new QName("http://schemas.xmlsoap.org/soap/envelope/",
  System.out.println("Most likely a net error: " + x.getFaultString());
  System.out.println("SOAP Fault: " + x.getFaultCode() + ", " 
                    + x.getFaultString());


If you don't want your phone to keep ringing due to network misconfiguration, make sure your Web service client returns sensible messages for network errors. In its present form, JAX-RPC does not help, but as this tip demonstrates you can work around those limitations.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into XML on developerWorks

Zone=XML, SOA and web services
ArticleTitle=Tip: Make SOAP and Web servers cohabit peacefully