Home » Enterprise Java » Web Services » JAX-WS » JAX-WS Exceptions and Faults: Annotation, Exception and Fault Handling Examples

8 Flares Twitter 1 Facebook 0 Google+ 6 LinkedIn 1 Email -- Filament.io 8 Flares ×

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.
java JAX-WS exception fault handling example

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 <em>greetMe()</em> which accepts a name parameter and throws a custom <em>MyServiceException</em> 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.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Generated by JAX-WS RI at http://jax-ws.dev.java.net. RI's version is JAX-WS RI 2.1.3-b02-. -->
<definitions targetNamespace="http://ws.globinch.com/" name="MyService" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://ws.globinch.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <types>
    <xsd:schema>
      <xsd:import namespace="http://ws.globinch.com/" schemaLocation="MyService_schema1.xsd"/>
    </xsd:schema>
  </types>
  <message name="greetMe">
    <part name="parameters" element="tns:greetMe"/>
  </message>
  <message name="greetMeResponse">
    <part name="parameters" element="tns:greetMeResponse"/>
  </message>
  <message name="MyServiceException">
    <part name="fault" element="tns:MyServiceFault"/>
  </message>
  <portType name="MyServiceImpl">
    <operation name="greetMe">
      <input message="tns:greetMe"/>
      <output message="tns:greetMeResponse"/>
      <fault message="tns:MyServiceException" name="MyServiceException"/>
    </operation>
  </portType>
  <binding name="MyServiceServiceBinding" type="tns:MyServiceImpl">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="greetMe">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="MyServiceException">
        <soap:fault name="MyServiceException" use="literal"/>
      </fault>
    </operation>
  </binding>
  <service name="MyService">
    <port name="MyServiceService" binding="tns:MyServiceServiceBinding">
      <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
    </port>
  </service>
</definitions>

And the XML schema is below.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" targetNamespace="http://ws.globinch.com/" xmlns:tns="http://ws.globinch.com/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="MyServiceFault" nillable="true" type="tns:myServiceFault"/>

  <xs:element name="greetMe" type="tns:greetMe"/>

  <xs:element name="greetMeResponse" type="tns:greetMeResponse"/>

  <xs:complexType name="greetMe">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="greetMeResponse">
    <xs:sequence>
      <xs:element name="return" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="myServiceFault">
    <xs:sequence>
      <xs:element name="faultCode" type="xs:string" minOccurs="0"/>
      <xs:element name="faultString" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.globinch.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:greetMe>
          <name>Binu George</name>
      </ws:greetMe>
   </soapenv:Body>
</soapenv:Envelope>

Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:greetMeResponse xmlns:ns2="http://ws.globinch.com/">
         <return>Hello Binu George</return>
      </ns2:greetMeResponse>
   </S:Body>
</S:Envelope>

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

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.globinch.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:greetMe>
          <name>fault</name>
      </ws:greetMe>
   </soapenv:Body>
</soapenv:Envelope>

Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <S:Fault xmlns:ns4="http://www.w3.org/2003/05/soap-envelope">
         <faultcode>S:Server</faultcode>
         <faultstring>My Service Error</faultstring>
         <detail>
            <ns2:MyServiceFault xmlns:ns2="http://ws.globinch.com/">
               <faultCode>1234</faultCode>
               <faultString>My Service Error</faultString>
            </ns2:MyServiceFault>
         </detail>
      </S:Fault>
   </S:Body>
</S:Envelope>

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

Incoming search terms:

8 Flares Twitter 1 Facebook 0 Google+ 6 LinkedIn 1 Email -- Filament.io 8 Flares ×

About Binu George

7 thoughts on “JAX-WS Exceptions and Faults: Annotation, Exception and Fault Handling Examples

  1. Giuseppe Tino says:

    Hi, I followed your example (and other that I found on the net) but I’m still unable to have custom exceptions in my web services.
    I’m using Netbeans 7.3.1 to develop, deploy and run my web application. The server is glassfish 4.0 the JavaEE and the JDK that I choose for the netbeans project are JEE5 and JDK7.
    When I try to invoke the greetMe method of your example with a string as parameter all works properly but if I pass the String “fault” as parameter, I receive the following exception:
    WS00041: Service invocation threw an exception with message : null; Refer to the server log for more details
    Exceptions details : java.lang.reflect.InvocationTargetException
    javax.servlet.ServletException: java.lang.reflect.InvocationTargetException at org.glassfish.webservices.monitoring.WebServiceTesterServlet.doPost(WebServiceTesterServlet.java:336) at org.glassfish.webservices.monitoring.WebServiceTesterServlet.invoke(WebServiceTesterServlet.java:106) at org.glassfish.webservices.JAXWSServlet.doPost(JAXWSServlet.java:157) at javax.servlet.http.HttpServlet.service(HttpServlet.java:707) at javax.servlet.http.HttpServlet.service(HttpServlet.java:790) at org.apache.catalina.core.StandardWrapper.service(StandardWrapper.java:1682) at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:318) at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:160) at […]
    What can be wrong?
    Thanks in advance.

  2. Giuseppe Tino says:

    EDIT MY PREVIOUS MESSAGE:
    I tried to use TCPMon to send and receive the SOAP message to the web server and all works fine, so your example is correct.
    The error is on the client side, probably the generator of the class from WSDL doesn’t work well.
    This is the exception that the web service client throws when the webServer send a fault message:

    Exception in thread “main” java.lang.ExceptionInInitializerError
    at com.sun.xml.internal.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:107)
    at com.sun.xml.internal.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:78)
    at com.sun.xml.internal.ws.client.sei.SEIStub.invoke(SEIStub.java:129)
    at com.sun.proxy.$Proxy32.greetMe(Unknown Source)
    at testclientws.TestClientWS.greetMe(TestClientWS.java:28)
    at testclientws.TestClientWS.main(TestClientWS.java:18)
    Caused by: java.lang.ClassCastException: com.sun.xml.bind.v2.runtime.JAXBContextImpl cannot be cast to com.sun.xml.internal.bind.api.JAXBRIContext
    at com.sun.xml.internal.ws.fault.SOAPFaultBuilder.(SOAPFaultBuilder.java:550)
    … 6 more
    Java Result: 1

  3. Giuseppe Tino says:

    EDIT/SOLVED:
    It was a library problem. I tried to add the JAX_WS 2.2.6 libraries on the client and all works fine.
    Sorry for the multiple posts.
    Thanks a lot for your example.

  4. Binu George says:

    Hi Guiseppe,
    Glad to hear that the problem is solved. I was little busy with my regular job and could not reply you promptly.

    Thank You
    Binu George

  5. TonyPrep says:

    Thanks for the great article. Just one point: the code that sets up the fault in the greetMe() implementation is not needed, since it isn’t actually used and the constructor for the exception creates the fault internally. Alternative, a different constructor can be used in greetMe; the constructor that passes a fault.

  6. Andrew Gibson says:

    Hi Binu, I’ve been working with jax-ws for a while and have encountered an issue which you or someone who follows your blog, might be able to shed some light on. I’ve had no problems running the code in this example, but when I add a wsdl policy requiring (Mutual Certificate Security) the signing of the request and response payloads I’m encountering a problem with signing SOAP Faults.

    When the service returns normally (ie: when it doesn’t throw a SOAP Fault), the response is signed correctly, and the client has no problem validating the signature. However, when I throw an exception and return a SOAP Fault (which I also enforce signing for), the client throws a WSSecurityException stating “the signature or decryption was invalid”. Have you ever encountered this issue?

    I would be grateful for any help/suggestions.

  7. seo specialist london says:

    Great site you have got here.. It’s difficult to find high-quality writing like yours these days.
    I seriously appreciate people like you! Take care!!

Leave a Reply

Your email address will not be published. Required fields are marked *

Paged comment generated by AJAX Comment Page

Google+ Plus Follow on Twitter Like On Facebook Linked Follow

Popular post

JAX-WS Web Services and Clients Java JAX-WS Tutorial: Develop Web Services and Clients (Consumers) Using JAX-WS
jax-ws usernametoken example JAX-WS and Secure Java Web Services using UsernameToken : WS-Security with Metro and WSIT
How to Fix : java.security.cert.CertificateException: No name matching localhost found
JAX-WS exception fault handling example JAX-WS Exceptions and Faults: Annotation, Exception and Fault Handling Examples
SOAP Binding: Difference between Document and RPC Style Web Services

Subscribe to Enterprise Java newsletter
Subscribe
Get Enterprise Java Newsletter

Enter your email and stay on top of things,