In my previous article, I showed you how to create a simple web service and deploy it. In this article I’ll show you the basics of Exception handling using JAX-WS.

For quick reference, here’s how the Web Service looked in the last article:

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

// The url will now be .../HelloService
@WebService(serviceName="HelloService") 
public class SimpleWebService {
    // The method element in the XML will now be SayHello
    @WebMethod(operationName="SayHello") 
    // @WebParam will rename the input from arg0 to name
    public String sayHello(@WebParam(name="name") String name){
        return "Hello " + name + "!";
    }
}

And this is the basic client I’ll start with for testing it, for information about creating a web service client in NetBeans click here:

import simon.webservice.*;

public class SimpleClient {

    public static void main(String[] args) {
        try{
            HelloService service = new HelloService();
            SimpleWebService port = service.getSimpleWebServicePort();

            System.out.println(port.sayHello("Fault"));

        }catch(Exception e){
            System.err.println(e.getMessage());
        }
    }
}

When this is ran with the current Web Service, it’ll say “Hello Fault!”

Throwing Our Own Exception

While just throwing an Exception can be done, this is a bad idea. It carries the issue of the generated Exception class clashing with java.lang.Exception unless they are explicitly referenced.

To get around this, we’ll make our own Exception that maps onto a SOAP fault. To be in compliance with section 2.5 of the JAX-WS specification our custom exception must:

Extend Exception.
Be annotated with @WebFault
Use a fault bean used to store the message
Implement the two constructors and the method described in the spec

Here’s the SimpleException class with the mothods required by the JAX-WS spec:

import javax.xml.ws.WebFault;

@WebFault(name="SimpleException")
public class SimpleException extends Exception{
    private SimpleExceptionBean faultBean;

    public SimpleException(String message, SimpleExceptionBean faultInfo){
        super(message);
        faultBean = faultInfo;
    }

    public SimpleException(String message, SimpleExceptionBean faultInfo, Throwable cause) {
        super(message, cause);
        faultBean = faultInfo;
    }

    public SimpleExceptionBean getFaultInfo(){
        return faultBean;
    }
}

The fault bean, which is a plain old java object (POJO):

public class SimpleExceptionBean {
    private String message;

    public SimpleExceptionBean() {
    }
    public SimpleExceptionBean(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

}

Now we need to modify the SimpleWebService to throw our Exception, to do this we can modify the sayHello method:

@WebMethod(operationName="SayHello") 
// @WebParam will rename the input from arg0 to name
public String sayHello(@WebParam(name="name") String name) throws SimpleException{
    if(name.equalsIgnoreCase("fault")){
        throw new SimpleException("Fault Detected", new SimpleExceptionBean());
    }
    return "Hello " + name + "!";
}

Now when we run the client, we’ll get “Fault Detected” printed out to System.err. As Faults are mapped to Exception by JAX, the catch clause in the client doesn’t need to be modified to handle the Exception mapped to the Fault.

Got any questions? Ask them below.