Given a set of requirements, create code to handle system and service exceptions and faults received by a Web services client.


WSDL-to-Java mapping

Let's look at the WSDL-to-Java mapping of faults to exceptions, starting with the WSDL. Run your favorite JAX-WS WSDL-to-Java code generator on this WSDL. It gives you the generated interface and fault classes.

<wsdl:definitions targetNamespace="urn:fault.sample"
    xmlns:tns="urn:fault.sample" xmlns:wsdl=""
    <xsd:schema targetNamespace="urn:fault.sample"
        xmlns:tns="urn:fault.sample" xmlns:xsd="">
      <xsd:element name="op" type="tns:Op"/>
      <xsd:complexType name="Op">
          <xsd:element name="in" type="xsd:string"/>
      <xsd:element name="opResponse" type="tns:OpResponse"/>
      <xsd:complexType name="OpResponse">
          <xsd:element name="out" type="xsd:string"/>
      <xsd:element name="faultElement" type="tns:Fault"/>
      <xsd:complexType name="Fault">
          <xsd:element name="code" type="xsd:string"/>
  <wsdl:message name="opRequest">
    <wsdl:part name="parameters" element="tns:op"/>
  <wsdl:message name="opResponse">
    <wsdl:part name="parameters" element="tns:opResponse"/>
  <wsdl:message name="faultMsg">
    <wsdl:part name="parameters" element="tns:faultElement"/>
  <wsdl:portType name="PT">
    <wsdl:operation name="op">
      <wsdl:input message="tns:opRequest"/>
      <wsdl:output message="tns:opResponse"/>
      <wsdl:fault name="fault" message="tns:faultMsg"/>
  <wsdl:binding name="Binding" type="tns:PT">
    <soap:binding style="document" transport=""/>
    <wsdl:operation name="op">
      <soap:operation soapAction=""/>
        <soap:body use="literal"/>
        <soap:body use="literal"/>
      <wsdl:fault name="fault">
        <soap:fault use="literal" name="fault"/>
  <wsdl:service name="Service">
    <wsdl:port name="Port" binding="tns:Binding">
      <soap:address location=""/>


Generated Java interface:

package sample.fault;

public interface PT {
    public String op(String in) throws FaultMsg;

The Java exception name is derived from the WSDL fault message's name; in this case FaultMsg:

package sample.fault;

public class FaultMsg extends Exception {
    private Fault faultInfo;
    public FaultMsg(String message, Fault faultInfo) {...}
    public FaultMsg(String message, Fault faultInfo, Throwable cause) {...}
    public Fault getFaultInfo() {...}

All mapped JAX-WS exceptions contain a private faultInfo instance variable. The type of this faultInfo is derived from the schema, which the fault's wrapper element refers to; in this case it's Fault:

package sample.fault;

public class Fault {
    protected String code;
    public String getCode() {...}
    public void setCode(String value) {...}

Why does a JAX-WS mapping of faults create a fault class and a fault info class? The reason is that JAX-WS delegates the generation of schema mappings to Java Architecture for XML Binding (JAXB). JAX-WS knows how to do Web services stuff, but it doesn't know how to do schema stuff. JAXB knows schema. A fault or exception is a Web services artifact. The data in a fault is a schema artifact. So the JAX-WS generator generates the exception, and the JAXB generator generates the Java bean containing the exception's data.

Java-to-WSDL mapping

JAX-WS seems to prefer that you build exceptions like the ones it generates, with the exception itself separate from the Java bean data for the exception. If you follow this pattern, you get the reverse of the mapping described in the previous section.

But separating the exception data from the exception is not typical of how a Java programmer writes exceptions. So JAX-WS also provides a mapping for the more natural exception. A simple example of this natural pattern is shown below.


package sample2.fault;

public interface PT {
  public String op(String in) throws Fault;

Exception: package sample2.fault; public class Fault extends Exception { public Fault(String code) {...} public String getCode() {...} public void setCode(String value) {...} }

WSDL generated from above Java:

<definitions targetNamespace="http://fault.sample2/"
    xmlns:tns="http://fault.sample2/" xmlns=""
  <message name="op">
    <part element="tns:op" name="parameters"/>
  <message name="opResponse">
    <part element="tns:opResponse" name="parameters"/>
  <message name="Fault">
    <part element="tns:Fault" name="fault"/>
  <portType name="PTImpl">
    <operation name="op">
      <input message="tns:op"/>
      <output message="tns:opResponse"/>
      <fault message="tns:Fault" name="Fault"/>
  <binding name="PTImplPortBinding" type="tns:PTImpl">
    <soap:binding style="document" transport=""/>
    <operation name="op">
      <soap:operation soapAction=""/>
        <soap:body use="literal"/>
        <soap:body use="literal"/>
      <fault name="Fault">
        <soap:fault name="Fault" use="literal"/>
  <service name="PTImplService">
    <port binding="tns:PTImplPortBinding" name="PTImplPort">
      <soap:address location="https://localhost:9444/SampleFault/PTImplService"/>

Schema generated from above Java:

<xs:schema targetNamespace="http://fault.sample2/"
        xmlns:xs="" xmlns:tns="http://fault.sample2/">

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

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

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

  <xs:complexType name="op">
      <xs:element minOccurs="0" name="arg0" type="xs:string"/>

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

  <xs:complexType name="Fault">
      <xs:element minOccurs="0" name="code" type="xs:string"/>
      <xs:element minOccurs="0" name="message" type="xs:string"/>

Unmodeled faults

What happens when an unmodeled fault occurs? For example, what happens when the service above throws an exception other than sample2.fault.Fault (for instance, NullPointerException)? What happens on the client? The answer to that depends on the messaging protocol. For instance, when communicating via SOAP/HTTP, the server-side SOAP engine creates a SOAP message containing a SOAP fault with information relevant to the problem in the faultcode and faultstring fields:

<soapenv:Envelope xmlns:soapenv="">


Because a SOAP fault is returned to the client, JAX-WS has defined an exception named SOAPFaultException. When the service throws an unmodeled fault, the client receives a SOAPFaultException. is a protocol-specific exception. It extends JAX-WS defines another extension of ProtocolException: for the XML/HTTP communication channel. Those are the only standardized bindings defined for WSDL. For other bindings, assume the binding provider defines other extensions of ProtocolException, one for each new binding.

JAX-WS defines a number of Java classes, such as Service, BindingProvider, and Dispatch. If calls to those classes fail, they throw WebServiceException, the general-purpose exception for the JAX-WS APIs.

  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by java.lang.RuntimeException
              extended by
                  extended by
                      extended by
                      extended by

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCDJWS 1.4 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     SCDJWS 5.0 Quiz