Make SOAP and Web servers cohabit peacefully

First published by IBM at http://www-106.ibm.com/developerworks/xml/library/x-tipherr.htm

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

public void printSOAPException(SOAPException x)
{
 Throwable cause = x.getCause();
 if(cause != null && cause instanceof AxisFault)
   printAxisFault((AxisFault)cause);
 else if(cause != null)
   System.out.println(x.getClass().getName()
                     + " exception chained: "
                     + x.getMessage());
 else
   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 =
      x.lookupFaultDetail(
        new QName("http://xml.apache.org/axis/","HttpErrorCode"));
   if(null != e)
   {
      e.normalize();
      String httpErrorCode = e.getFirstChild().getNodeValue().trim();
      if(httpErrorCode.equals("407"))
         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)");
      else
         System.out.println(x.getFaultString());
   }
   else
      System.out.println("Network error: " + x.getFaultString());
 }
 else if(x.getFaultCode().equals(
          new QName("http://schemas.xmlsoap.org/soap/envelope/",
                    "Server.userException")))
  System.out.println("Most likely a net error: " + x.getFaultString());
 else
  System.out.println("SOAP Fault: " + x.getFaultCode() + ", " 
                    + x.getFaultString());
}

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

Resources

• Participate in the discussion forum for Benoît Marchal's Working XML column.
  
  
• Pick up useful insights on connection issues in "Questions on HttpURLConnection and Proxies" by Benoît Marchal, even though it does not specifically address SOAP.
  
  
• Read "The Impact of Site Finder on Web Services" by Steve Loughran, a useful discussion on the relationship between Web services and the Web infrastructure.
  
  
• Learn more about the relationship between SOAP and Web servers in "Soapbox: Why I'm using SOAP" by Benoît Marchal (developerWorks, February 2001).
  
  
• Turn to the W3C for the lowdown on SOAP—check out their XML Protocol Working Group page. You might also want to look at their official primer on SOAP.
  
  
• Get an introduction to SOAP with James Snell's article "Reflections on SOAP" (developerWorks, April 2001).
  
  
• Get the latest version of Axis from the Apache Web site.
  
  
• "Web services architect" (developerWorks, April 2001) by Dan Gisolfi points you to useful information on Web services architecture.
  
  
• Section 10 of the HTTP 1.1 RFC lists the status codes. You will want to test against some of those, particularly those related to proxies and gateways.
  
  
• Find more XML resources on the developerWorks XML zone. For a complete list of XML tips to date, check out the tips summary page.
  
  
• Sign up for the weekly developerWorks Web services/XML Tips newsletter.
  
  
• Buy Benoît Marchal's book Applied XML Solutions at the developerWorks Developer Bookstore.
  
  
• Learn how you can become an IBM Certified Developer in XML and related technologies.