Fault and exception processing on the Web Service

The WSDL faults and Java exceptions are mapped according to the JAX-WS 2.2 specifications. The following figure shows an example of mapping between the WSDL faults and Java exception classes.

Figure 10-7 Example of mapping between WSDL faults and Java exception classes

[Figure]

In the mapping example, you learn that the UserDefinedFault fault is mapped to the fault bean (com.example.sample.UserDefinedFault) and the wrapper exception class (com.example.sample.UserDefinedException).

For the mapping between the fault and exception classes, see 15.1.7 Mapping the fault to the exception class and 16.1.7 Mapping the Java wrapper exception class to the fault.

Using the JAX-WS engine on the Web Service, the wrapper exception class is bound to the SOAP fault as described in the following table:

Table 10-6 Wrapper exception class binding

No.	Child element of the SOAP fault		Contents
No.	SOAP 1.1 specifications	SOAP 1.2 specifications	Contents
1	faultcode	soapenv12:Code	SOAP 1.1 specifications Fixed to QName soapenv:server. SOAP 1.2 specifications Fixed to QName soapenv 12:Receiver
2	faultstring	soapenv12:Reason	Results in the execution of the getMessage method for the wrapper exception class.
3	faultactor	soapenv12:Role	Does not exist.
4	detail	soapenv12:Detail	Results in the marshalling of the fault bean.

The following is an example of a wrapper exception class in the Web Service Implementation Class:

//Generate the fault bean and specify the information you want marshlling
UserDefinedFault fault = new UserDefinedFault();
fault.additionalInfo = 257;
fault.detail = "Failed by some reason.";
fault.message = "Contact your administrator.";
 
//wrapper exception class is thrown
throw new UserDefinedException(
 "Something happens.", fault );

The following is an example of a SOAP fault message of the SOAP 1.1 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
 <ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns2:Server</faultcode>
 <faultstring>Something happens.</faultstring>
 <detail>
 <ns2:UserDefinedFault xmlns:ns2="http://example.com/sample">
 <additionalInfo>257</additionalInfo>
 <detail>Failed by some reason.</detail>
 <message>Contact your administrator.</message>
 </ns2:UserDefinedFault>
 </detail>
 </ns2:Fault>
 </S:Body>
</S:Envelope>

#: A SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

The following is an example of a SOAP fault message of the SOAP 1.2 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <ns3:Code>
        <ns3:Value>ns3:Receiver</ns3:Value>
      </ns3:Code>
      <ns3:Reason>
        <ns3:Text xml:lang="ja">Something happens.</ns3:Text>
      </ns3:Reason>
      <ns3:Detail>
        <env:UserDefinedFault xmlns:env="http://example.com/sample">
          <additionalInfo>257</additionalInfo>
          <detail>Failed by some reason.</detail>
          <message>Contact your administrator.</message>
        </env:UserDefinedFault>
      </ns3:Detail>
    </ns3:Fault>
  </S:Body>
</S:Envelope>

#: A SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

(2) Runtime exception binding

If a runtime exception other than javax.xml.ws.WebServiceException is thrown in the Web Service Implementation Class, the runtime exception is bound to the SOAP fault by the JAX-WS engine on the Web Service (binding based on the JAX-WS 2.2 specifications).

The following table describes an example of runtime exception binding:

Table 10-7 Runtime exception binding

No.	Child element of the SOAP fault		Contents
No.	SOAP 1.1 specifications	SOAP 1.2 specifications	Contents
1	faultcode	soapenv12:Code	SOAP 1.1 specifications Fixed to QName soapenv:server. SOAP 1.2 specifications . Fixed to QName soapenv 12:Receiver
2	faultstring	soapenv12:Reason	Results in the execution of the getMessage method for the wrapper exception class.
3	faultactor	soapenv12:Role	Does not exist.
4	detail	soapenv12:Detail	Results in the marshalling of the fault bean.

The following is an example of a runtime exception:

//runtime exception is thrown
throw new IllegalArgumentException( "Something illegal." );

The following is an example of a SOAP fault message of the SOAP 1.1 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
 <ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns2:Server</faultcode>
 <faultstring>Something illegal.</faultstring>
 </ns2:Fault>
 </S:Body>
</S:Envelope>

#: A SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

The following is an example of a SOAP fault message of the SOAP 1.2 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <ns3:Code>
        <ns3:Value>ns3:Receiver</ns3:Value>
      </ns3:Code>
      <ns3:Reason>
        <ns3:Text xml:lang="ja">Something illegal.</ns3:Text>
      </ns3:Reason>
    </ns3:Fault>
  </S:Body>
</S:Envelope>

#: The SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

(3) javax.xml.ws.WebServiceException binding

If javax.xml.ws.WebServiceException other than javax.xml.ws.soap.SOAPFaultException is thrown in the Web Service Implementation Class or the Provider Implementation Class, javax.xml.ws.WebServiceException is bound to the SOAP fault by the JAX-WS engine on the Web Service (binding based on the JAX-WS 2.2 specifications).

The following table describes an example of javax.xml.ws.WebServiceException binding:

Table 10-8 javax.xml.ws.WebServiceException binding

No.	Child element of the SOAP fault		Contents
No.	SOAP 1.1 specifications	SOAP 1.2 specifications	Contents
1	faultcode	soapenv12:Code	SOAP 1.1 specifications Fixed to QName soapenv:server. SOAP 1.2 specifications Fixed to QName soapenv12:Receiver.
2	faultstring	soapenv12:Reason	Results in the execution of the getMessage method for the wrapper exception class. For SOAP 1.2, the default locale of JavaVM is set in the xml:lang attribute.
3	faultactor	soapenv12:Role	Does not exist.
4	detail	soapenv12:Detail	Results in the marshalling of the fault bean.

The following is an example of the javax.xml.ws.WebServiceException:

//javax.xml.ws.WebServiceException is thrown
throw new javax.xml.ws.WebServiceException( "Web Service Exception." );

The following is an example of a SOAP fault message of the SOAP 1.1 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
 <ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
 <faultcode>ns2:Server</faultcode>
 <faultstring>Web Service Exception.</faultstring>
 </ns2:Fault>
 </S:Body>
</S:Envelope>

#: The SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

The following is an example of a SOAP fault message of the SOAP 1.2 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/
               xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <ns3:Code>
        <ns3:Value>ns3:Receiver</ns3:Value>
      </ns3:Code>
      <ns3:Reason>
        <ns3:Text xml:lang="ja">Something illegal.</ns3:Text>
      </ns3:Reason>
    </ns3:Fault>
  </S:Body>
</S:Envelope>

#: The SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

(4) javax.xml.ws.soap.SOAPFaultException binding

If javax.xml.ws.soap.SOAPFaultException is thrown in the Web Service Implementation Class or the Provider Implementation Class, the javax.xml.ws.soap.SOAPFaultException is bound to the SOAP fault by the JAX-WS engine on the Web Service (binding based on the JAX-WS 2.2specifications).

The following table describes an example of javax.xml.ws.soap.SOAPFaultException binding:

Table 10-9 javax.xml.ws.soap.SOAPFaultException binding

No.	Child element of the SOAP fault		Contents
No.	SOAP 1.1 specifications	SOAP 1.2 specifications	Contents
1	faultcode	soapenv12:Code	SOAP 1.1 specifications Results in the getFault().getFaultCodeAsQName method. However, for null, fixed to QName soapenv:server. SOAP 1.2 specifications Fixed to QName soapenv12:Sender. The child element soapenv12:Subcode of soapenv12:Code maintains the result.
2	faultstring	soapenv12:Reason	Results in the getFaultReasonText method. However, for null, results in the execution of the getMessage method.
3	faultactor	soapenv12:Role	Results in the getFault().getFaultRole method. However, for null, does not exist.
4	detail	soapenv12:Detail	Results in the marshalling of the results of the execution of the getFault().getDetail method. However, for null, does not exist.

The following is an example of javax.xml.ws.soap.SOAPFaultException for the SOAP 1.1 specifications:

SOAPFault soapFault = ...;
soapFault.setFaultCode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultActor( "http://example.com/sample" );
soapFault.setFaultString( "SOAPFaultException happens." );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );
 
//javax.xml.ws.soap.SOAPFaultException is thrown
throw new SOAPFaultException( soapFault );

The following is an example of javax.xml.ws.soap.SOAPFaultException for the SOAP 1.2 specifications:

SOAPFactory soapFactory = SOAPFactory.newInstance( SOAPConstants.SOAP_1_2_PROTOCOL );
SOAPFault soapFault = soapFactory.createFault();
soapFault.appendFaultSubcode( new QName( "http://sample.org", "UserDefined" ) );
soapFault.setFaultRole( "http://example.com/sample" );
soapFault.addFaultReasonText( "SOAPFaultException happens.", Locale.getDefault() );
Detail detail = soapFault.addDetail();
SOAPElement soapElement = detail.addChildElement( new QName( "", "detailTest" ) );
soapElement.addTextNode( "TEST." );
 
//javax.xml.ws.soap.SOAPFaultException is thrown
throw new SOAPFaultException( soapFault );

The following is an example of a SOAP fault message of the SOAP 1.1 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
     <faultcode xmlns:ns0="http://sample.org">ns0:UserDefined</faultcode>
     <faultstring>SOAPFaultException happens.</faultstring>
     <faultactor>http://example.com/sample</faultactor>
     <detail><detailTest>TEST.</detailTest></detail>
    </ns2:Fault>
  </S:Body>
</S:Envelope>

#: The SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

The following is an example of a SOAP fault message of the SOAP 1.2 specifications that will be sent (actually, there is no linefeed and indent):

<?xml version="1.0" ?>
<S:Envelope xmlns:S= "http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ns3="http://www.w3.org/2003/05/soap-envelope">
      <ns3:Code>
        <ns3:Value>ns3:Sender</ns3:Value>
        <ns3:Subcode>
          <ns3:Value xmlns:ns0="http://sample.org">ns0:UserDefined</ns3:Value>
        </ns3:Subcode>
      </ns3:Code>
      <ns3:Reason>
        <ns3:Text xml:lang="ja">SOAPFaultException happens.</ns3:Text>
      </ns3:Reason>
      <ns3:Role>http://example.com/sample</ns3:Role>
      <ns3:Detail>
        <env:Detail xmlns:env="http://www.w3.org/2003/05/soap-envelope">
          <detailTest>TEST.</detailTest>
        </env:Detail>
      </ns3:Detail>
    </ns3:Fault>
  </S:Body>
</S:Envelope>

#: The SOAP fault message always includes the namespace definition of the SOAP 1.1 and SOAP 1.2 specifications.

10.4.1 Fault and exception processing on the Web Service

(1) Processing of service-specific exceptions

(2) Runtime exception binding

(3) javax.xml.ws.WebServiceException binding

(4) javax.xml.ws.soap.SOAPFaultException binding