Fault Messages

In service-oriented applications, SOAP clients expect a fault message to be returned when an error occurs during processing. A fault message is a SOAP message.

A fault message has the following subelements:

Subelement Description
faultcode A code that identifies the fault.
faultstring An explanation of the fault.
faultactor Information about what caused the fault to occur.
detail Application-specific information about the fault.

Fault messages defined in the WSDL file are called declared faults. Fault messages that are not defined in the WSDL file are called undeclared faults. The process for generating a fault message is implementation dependent and typically depends on whether the fault is declared or not.

Declared Faults

A service can define multiple fault messages for any operation. When an error occurs, it will return a fault message to indicate the specific error.

Example WSDL File

The following WSDL fragment shows the getWeather operation with two declared faults: orderFault and orderFault2. The detail element for the orderFault message contains a ZipCodeFault element. The detail element for the orderFault2 message contains a CityFault element. 

<wsdl:types>

  <schema xmlns="http://www.w3.org/2001/XMLSchema" 

  xmlns:tns="http://www.example.org/weatherschema" 

  targetNamespace="http://www.example.org/weatherschema" elementFormDefault="unqualified" 

  attributeFormDefault="unqualified">

    <complexType name="WeatherRequestType">

       <sequence>

         <element name="city" type="string"/>

         <element name="state" type="string"/>

         <element name="zip" type="string"/>

       </sequence>

    </complexType>

    <complexType name="WeatherResponseType">

       <sequence>

         <element name="high" type="float"/>

         <element name="low" type="float"/>

         <element name="forecast" type="string"/>

       </sequence>

    </complexType>



    <element name="WeatherRequest" type="tns:WeatherRequestType"/>

    <element name="WeatherResponse" type="tns:WeatherResponseType"/>

    <element name="ZipCodeFault" type="string"/>

    <element name="CityFault" type="string" /> 

  </schema>

</wsdl:types>

<wsdl:message name="invalidZipCodeFault">

  <wsdl:part name="error" element="ns0:ZipCodeFault"/>

</wsdl:message>

<wsdl:message name="invalidCityFault">

  <wsdl:part name="error" element="ns0:CityFault" /> 

</wsdl:message>

<wsdl:portType name="WeatherReportPT">

 <wsdl:operation name="GetWeather">

  <wsdl:input message="tns:GetWeatherRequest"/>

  <wsdl:output message="tns:GetWeatherResponse"/>

  <wsdl:fault name="orderFault" message="tns:invalidZipCodeFault"/>

  <wsdl:fault name="orderFault2" message="tns:invalidCityFault" /> 

 </wsdl:operation>

</wsdl:portType>

Example Declared Fault Message

The following is a sample of an invalidZipCodeFault message. The SOAP Fault element contains error information within a SOAP message. 

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

  <faultcode xmlns="">SOAP-ENV:soap:Server</faultcode>

  <faultstring xmlns="">Could not find the zip code</faultstring\>

  <faultactor xmlns="">http://www.weather.com/forecast</faultactor>

  <detail xmlns="">

    <ns:ZipCodeFault xmlns:xs="http://www.w3.org/2001/XMLSchema" 

     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

     xmlns:ns="http://www.example.org/weatherschema" 

     xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">94305</ns:ZipCodeFault>

  </detail>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Undeclared Faults

Undeclared faults are handled in an implementation-dependent fashion.

Example Undeclared Fault Message

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>

 <SOAP-ENV:Fault>

  <faultcode>SOAP-ENV:Server</faultcode>

  <faultstring>java.lang.RuntimeException: Undeclared fault....</faultstring>

  <faultactor>DefaultRole</faultactor>

   <detail>

     <tibco:myFaultDetail xmlns:tibco="http://tibcouri/">

     org.osoa.sca.ServiceRuntimeException: java.lang.RuntimeException: Undeclared fault....

     at com.tibco.amf.platform.runtime.componentframework.internal.proxies.

      ProxyInvocationHandler.invoke(ProxyInvocationHandler.java:473)

     at $Proxy21.invoke(Unknown Source)

     at com.tibco.amf.binding.soap.runtime.transport.http.SoapHttpInboundEndpoint.

       processHttpPost(SoapHttpInboundEndpoint.java:250)

     at com.tibco.amf.binding.soap.runtime.transport.http.SoapHttpServer.doPost(

       SoapHttpServer.java:103)  

     ...

    Caused by: java.lang.RuntimeException: Undeclared fault....

     at com.sample.faultservice.Component1.getWeather(Component1.java:50)

     at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

     at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)

     at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

     at java.lang.reflect.Method.invoke(Method.java:585)

     at com.tibco.amf.platform.runtime.componentframework.internal.proxies.

       ProxyInvocationHandler.invoke(ProxyInvocationHandler.java:426)

     ... 20 more

     </tibco:myFaultDetail>

   </detail>

  </SOAP-ENV:Fault>

 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>
Contents
Search Results