evermind Blog

(This is an article from 2009 saved from the old wiki)

The handling of exceptions in JAX-WS is described at http://www.ibm.com/developerworks/webservices/library/ws-tip-jaxrpc.html. This documents describes the behaviour of Apache CXF (Version 2.2.3) when using the Java-first approach.

Normally a RuntimeExceptions and subclasses of these are converted to a „Fault“ without any further details (except the exception message). The original class name of the exception and any extra properties are lost. Checked exceptions and their properties are described in the WSDL. When they occur, the exception type all properties are added as detail to the soap fault. On the client side the correct exception is initialized, filled with the original properties and thrown.

Example of an unchecked exception:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Invalid credentials. Access denied.</faultstring>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Example of checked exception:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Invalid credentials. Access denied.</faultstring>
         <detail>
            <ns1:ServiceException xmlns:ns1="http://admin.service.ika.de/">
               <errorCode>LOGIN_FAILED</errorCode>
            </ns1:ServiceException>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

This in CXF behaviour is caused by the following things:

• The service interface is inspected when the service description is generated. This information is used to build the WSDL. The method signature is read by the ReflectionServiceFactoryBean (normally it’s subclass JaxWsServiceFactoryBean) when executing the method „protected void initializeFaults(final InterfaceInfo service, final OperationInfo op, final Method method)“.
• The implementation is inspected when a fault occurs to determine if the fault is FaultMode.CHECKED_APPLICATION_FAULT or FaultMode.UNCHECKED_APPLICATION_FAULT. This is done by the method invoker (normally a subclass of AbstractInvoker, default is JAXWSMethodInvoker). If the implementation method declares the thrown exception, it is handled as CHECKED_APPLICATION_FAULT

Only if the exception is known by the ServiceFactory and is considered to be a CHECKED_APPLICATION_FAULT, the type and all properties of the exception are send to the client. So if a developer declares a RuntimeException in the throws declaration of the service interface AND the implementation, it is handled exactly the same way as a checked exception.

Advantages of using unchecked remote exceptions

A checked exception must either be declared by a client method or be handled by it. If an application does exception handling on a very high level but remote calls on a low level, the exception must be declared everywhere. When the remote call is done in a method that overrides or implements an abstract method that not declares this exception, there’s no way for the implementing method to add the exception to the throws declaration. So it has either do deal with the exception or wrap it into a run time exception. Both makes client code more complex and unreadable.

Disadvantages of using unchecked remote exceptions

To make the exception work properly in, on the server side it has to be declared in the service interface and in the implementation. This is no problem for checked exceptions since they have to be declared in the implementation to allow that they are thrown and they have to be declared in the service interface to allow their declaration in the implementation. A run time exception can be thrown everywhere without declaration. So relying on these exceptions is very error prone (if the developer forgets to declare it on either the interface or implementation, it’s thrown as Fault on the client side).

Solutions to the problem above

One solution is to tell the service that any service method can throw certain kinds of RuntimeExceptions. So for every method these exceptions are described within the WSDL. The service must also know that when this exception occurs it should be handled as CHECKED_APPLICATION_FAULT. The easiest way to ensure both is to extend the ServiceFactory in two ways:

• 1st extend initializeFaults to add the run time exceptions to all service methods. The code here lacks a check if this exceptions are not already added.
• 2nd change the method invoker to handle these exceptions as CHECKED_APPLICATION_FAULT. Instead of implementing an own invoker, the original invoker is simlpy wrapped here and the message is changed if the cause of the fault is the expected run time exception.

import java.lang.reflect.Method;

import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.jaxws.support.JaxWsServiceFactoryBean;
import org.apache.cxf.message.Exchange;
import org.apache.cxf.message.FaultMode;
import org.apache.cxf.service.invoker.Invoker;
import org.apache.cxf.service.model.InterfaceInfo;
import org.apache.cxf.service.model.OperationInfo;

public class MyJaxWsServiceFactoryBean extends JaxWsServiceFactoryBean
{
    @Override
    protected void initializeFaults(final InterfaceInfo service, final OperationInfo op, final Method method)
    {
        super.initializeFaults(service,op,method);
        // TODO: only add if not declared by the method!
        addFault(service, op, MyCustomRuntimeException.class);
    }

    @Override
    public void setInvoker(Invoker invoker)
    {
        super.setInvoker(new InvokerWrapper(invoker));
    }

    protected static class InvokerWrapper implements Invoker
    {
        protected final Invoker target;
        protected InvokerWrapper(Invoker target)
        {
            this.target=target;
        }

        @Override
        public Object invoke(Exchange exchange, Object o)
        {
            try
            {
                return target.invoke(exchange, o);
            }
            catch (Fault fault)
            {
                if (fault.getCause() instanceof MyCustomRuntimeException)
                {
                    exchange.getInMessage().put(FaultMode.class,FaultMode.CHECKED_APPLICATION_FAULT);
                }
                throw fault;
            }
        }
    }
}

Using the custom service factory:
	<import resource="classpath:META-INF/cxf/cxf.xml" />
	<import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
	<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
	<jaxws:endpoint id="adminServiceEndpoint" implementor="#adminService" address="/admin">
		<jaxws:serviceFactory>
			<bean class="test.MyJaxWsServiceFactoryBean">
			</bean>
		</jaxws:serviceFactory>
	</jaxws:endpoint>