JAX-WS exception and SOAP fault handling sometimes confuses a Java programmer. This article explains the handling of JAX-WS exceptions and SOAP Fault with examples. Here, we also check some of the common Exceptions such as “IllegalAnnotationExceptions. java.lang.StackTraceElement does not have a no-arg default constructor.“. This article also discusses the JAX-WS mapping of WSDL faults to Java exceptions, Java exceptions to WSDL faults.

Pre-Requisites

You should have a basic knowledge on how to create JAX-WS web services and clients. You may find the following articles helpful.

1. Java JAX-WS Tutorial: Develop Web Services and Clients (Consumers) Using JAX-WS
2. SOAP Binding: Difference between Document and RPC Style Web Services
3. Logging or Tracing Web Service XML Request/Response with JAX-WS

More advanced features are discussed in the following articles

1. JAX-WS Attachment – Enable MTOM for JAX-WS Web services
2. JAX-WS Secure Web Services with Signatures and Encryption: WS-Security with Metro and WSIT
3. Secure Metro JAX-WS UsernameToken Web Service with Signature, Encryption and TLS (SSL)

Development tools required:

• Eclipse IDE
• Metro (or JAX-WS) latest version distribution
• JDK7
• Tomcat 6 or above

Quick info on JAX-WS Fault Handing and Exception Handling

The JAX-WS Specification demands that mapped exception MUST be annotated with a javax.xml.ws.WebFault annotation. A wsdl:fault element is mapped to this Java exception A wsdl:fault element refers to a wsdl:message that contains a single part and is mapped to a Java bean, called a fault bean , which is just a POJO. The exception class should have two constructors and a getter method (to obtain fault details) as follows

WrapperException(String message, FaultBean faultInfo)
WrapperException(String message, FaultBean faultInfo, Throwable cause)
FaultBean getFaultInfo()

Where, WrapperException is the name of the Exception class and FaultBean is the fault bean POJO.

The cause of JAX-WS Exceptions “IllegalAnnotationExceptions. java.lang.StackTraceElement does not have a no-arg default constructor”

Sometimes when you execute the “wsgen” tool to generate the web service artifacts you may encounter the following error, if you don’t implement JAX-WS exceptions and fault properly.

…………………………………..
Caused by: java.security.PrivilegedActionException: com.sun.xml.bind.v2.runtime.IllegalAnnotationsException: 1 counts of IllegalAnnotationExceptions
java.lang.StackTraceElement does not have a no-arg default constructor.
	this problem is related to the following location:
		at java.lang.StackTraceElement
		at public java.lang.StackTraceElement[] java.lang.Throwable.getStackTrace()
		at java.lang.Throwable
		at private java.lang.Throwable[] com.globinch.ws.jaxws.MyServiceExceptionBean.suppressed
		at com.globinch.ws.jaxws.MyServiceExceptionBean

	at java.security.AccessController.doPrivileged(Native Method)
	at com.sun.xml.ws.model.AbstractSEIModelImpl.createJAXBContext(AbstractSEIModelImpl.java:148)
	………………..

One possible reason for this error is, invalid use of custom exception in your JAX-WS web service implementations. This is because, Exceptions and Errors which are of “Throwable” objects cannot be serialized to XML because StackTraceElement doesn’t have a no-arg constructor. The no argument constructor is required by the JAXB runtime to generate the artifacts. You may be able to fix this by using @WebFault annotation on your exception class and by providing a FaultBean. Any Exception/Throwable class cannot be marshalled by JAXB due to the fact that StackTraceElement does not have a default constructor.
Another possible solution is to use @XmlTransient annotation on overridden methods that use StackTrace. The JAXB 2.2.5 and above versions will process the @XmlTrasient annotation in your custom class.

JAX-WS Exception Handling and JAX-WS SOAP Fault Handling Example

Now, let us create a web service and custom exception class to handle JAX-WS exception and SOAP faults.

Web Service SEI and Implementation Classes

The SEI interface has just one method greetMe() which accepts a name parameter and throws a custom MyServiceException exception.
/*
 * @(#)MyService.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.ws;

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

/**
 * The web service SEI.
 * 
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
@WebService
public interface MyService {

	@WebMethod
	public String greetMe(String name) throws MyServiceException;
}

In the implementation class, the greetMe() web service method throws MyServiceException if the incoming name if “fault”. Otherwise the service method returns a greeting message to the consumer.

/*
 * @(#)MyServiceImpl.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.ws;

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

/**
 * The web service implementation class.
 * 
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
@WebService(serviceName="MyService", portName="MyServiceService")
public class MyServiceImpl implements MyService {

	/**
	 * 
	 */
	public MyServiceImpl() {
		

	}

	/* (non-Javadoc)
	 * @see com.globinch.ws.MyService#greetMe(java.lang.String)
	 */
	@WebMethod
	
	public String greetMe(@WebParam(name="name") String name) throws MyServiceException {
		if(name.equalsIgnoreCase("fault")){
			MyServiceFault fault = new MyServiceFault();
			fault.setFaultCode("1234");
			fault.setFaultString("My Service Error");
			throw new MyServiceException("1234","My Service Error");
		}else{
			return "Hello "+name;
		}
		//return "Hello "+name;
	}

}

The Fault Bean.

This is the fault bean POJO class required by the JAXB runtime to process exceptions.

/*
 * @(#)MyServiceFault.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.ws;

/**
 * The MyServiceFault class.
 * 
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
public class MyServiceFault {
	/**
	 * Fault Code
	 */
	 private String faultCode;
	 /**
	  * Fault String
	  */
     private String faultString;
	/**
	 * @return the faultCode
	 */
	public String getFaultCode() {
		return faultCode;
	}
	/**
	 * @param faultCode the faultCode to set
	 */
	public void setFaultCode(String faultCode) {
		this.faultCode = faultCode;
	}
	/**
	 * @return the faultString
	 */
	public String getFaultString() {
		return faultString;
	}
	/**
	 * @param faultString the faultString to set
	 */
	public void setFaultString(String faultString) {
		this.faultString = faultString;
	}
	
}

Custom Exception class.

This class is required to be annotated with @WebFault annotation.

/*
 * @(#)MyServiceException.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.ws;

import javax.xml.ws.WebFault;

/**
 * The MyServiceException class.
 * 
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
@WebFault(name="MyServiceFault",targetNamespace="http://ws.globinch.com/")
public class MyServiceException extends Exception {

	
	/**
	 * 
	 */
	private static final long serialVersionUID = -6647544772732631047L;
	private MyServiceFault fault;
	/**
	 * 
	 */
	public MyServiceException() {
		// TODO Auto-generated constructor stub
	}
	/**
	 * 
	 * @param fault
	 */
	protected MyServiceException(MyServiceFault fault) {
        super(fault.getFaultString()); 
        this.fault = fault;
     }
	/**
	 * 
	 * @param message
	 * @param faultInfo
	 */
	public MyServiceException(String message, MyServiceFault faultInfo){
		super(message);
        this.fault = faultInfo;
	}
	/**
	 * 
	 * @param message
	 * @param faultInfo
	 * @param cause
	 */
	public MyServiceException(String message, MyServiceFault faultInfo, Throwable cause){
		super(message,cause);
        this.fault = faultInfo;
	}
	/**
	 * 
	 * @return
	 */
	public MyServiceFault getFaultInfo(){
		return fault;
	}
	
	/**
	 * @param message
	 */
	public MyServiceException(String message) {
		super(message);
		// TODO Auto-generated constructor stub
	}
	/**
	 * @param message
	 */
	public MyServiceException(String code, String message) {
		super(message);
		this.fault = new MyServiceFault();
	    this.fault.setFaultString(message);
	    this.fault.setFaultCode(code);
	}

	/**
	 * @param cause
	 */
	public MyServiceException(Throwable cause) {
		super(cause);
		// TODO Auto-generated constructor stub
	}

	/**
	 * @param message
	 * @param cause
	 */
	public MyServiceException(String message, Throwable cause) {
		super(message, cause);
		// TODO Auto-generated constructor stub
	}

}

You can create the WSDL of the above service, by using the “wsgen” tool or the web container will create one for you, if you package and deploy the service to a web container such as tomcat. Read the below article to know more about how to do that.
Java JAX-WS Tutorial: Develop Web Services and Clients (Consumers) Using JAX-WS

WSDL and Schema files

The WSDL should look like the following.

And the XML schema is below.

As we discussed above, the wsdl:fault element is mapped to our exception class MyServiceException. A wsdl:fault element refers to a wsdl:message that contains a single part and is mapped to a Java bean, called a fault bean , which is our MyServiceFault class.

JAX-WS exception handling example request and response

Now you can execute the service method greetMe() using a test class or tool such as SOAP UI. Let us first send a proper name as the request. The MyService response will greet you back.
Request

   
   
      
          Binu George
      
   

Response

   
      
         Hello Binu George
      
   

Now let us send the name as “fault” so that the service throws an excpetion with a erro code and error message.

Request

   
   
      
          fault
      
   

Response

   
      
         S:Server
         My Service Error
         
            
               1234
               My Service Error
            
         
      
   

You can see the response with proper fault code and fault message. The fault details gives the details of error as supplied by the web service method greetMe(). You may have to disable -Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace to avoid printing stacktrace as part of the response.
The above examples source files are not optimized or production ready. These are created just for learning purposes.

References

• JAX-WS Annotations
• JSR-000224 JAX_WS Specification