email article printer friendly get the code

Error-Proof Exception Handling
Learn how to properly code JAX-RPC–compliant Web services
by Shridhar Mysore

October 13, 2004

An important task in the Web services world is learning how to handle exceptions. Exception handling in JAX-RPC (Java API for XML-based RPC)–compliant Web services shouldn't be particularly tricky because the JAX-RPC spec governs such tasks. However, it is good to know some coding nuances for writing different types of clients (stubs-based vs. dynamic).

Although the market currently has a good number of implementers of the JAX-RPC spec, BEA WebLogic was one of the first to do so. Recently, exception handling in WebLogic Web services has undergone a facelift, mainly as the result of incorporating support for service-specific exception handling. Let's take a look at exception handling in BEA WebLogic Server Web services. To ensure that you are handling exceptions properly, we will cover relevant aspects of the spec, its implementation in BEA WebLogic Server, coding practices, and troubleshooting tips. First let's go over some nuts and bolts of exception handling.

Back to Basics
In Web services, an exception thrown by the Web service end point is passed on to the client as a SOAP fault. According to the JAX-RPC specification, a SOAP fault is mapped either to a javax.xml.rpc.soap.SOAPFaultException, a service-specific exception class, or a java.rmi.RemoteException.

Although some exceptions can be thrown from the server side:

java.lang.RuntimeException
java.rmi.RemoteException
javax.xml.rpc.soap.SOAPFaultException 
   (which extends java.lang.RuntimeException)
user-defined exceptions 
   (mapped to wsdl:fault in the WSDL).

on the client side, the following exceptions could be caught (including SOAPFaultException, but excluding java.lang.RuntimeException):

java.rmi.RemoteException
javax.xml.rpc.soap.SOAPFaultException
user-defined exceptions.

In Web Services Description Language (WSDL) the wsdl:fault element, which is an optional element in a wsdl:operation, specifies the abstract message format for any error messages that may be output as a result of a remote operation. According to the WSDL specification, a fault message must have a single part. A wsdl:fault is mapped to either a java.rmi.RemoteException (or its subclass), a service-specific Java exception, or a javax.xml.rpc.soap.SOAPFaultException.

Listing 1 shows an excerpt from a WSDL that defines a wsdl:fault. A wsdl:fault MyException is defined in the wsdl:operation sendSOAPFault, and the wsdl:fault message MyException is defined with a single part, which is mapped to a java:examples.webservices.basic.javaclass:MyException type.

A service-specific Java exception (mapped from a wsdl:fault and the corresponding wsdl:message) extends the class java.lang.Exception directly or indirectly. The single message part in the wsdl:message (referenced from the wsdl:fault element) may be either xsd:complexType or a simple XML type.

Now let's discuss the handling of SOAPFaultException and service-specific exceptions.

Handling SOAPFaultException
The SOAPFaultException represents a SOAP fault. This exception is thrown from the Java method mapped from the corresponding wsdl:operation.

The message part in the SOAP fault maps to the contents of the detail element that is accessible through the getDetail method on the SOAPFaultException. The method createDetail on the javax.xml.soap.SOAPFactory creates an instance of the javax.xml.soap.Detail. The faultstring provides a human-readable description of the SOAP fault. The faultcode element provides an algorithmic mapping of the SOAP fault.