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.

Note: A stack trace is included in the SOAP fault's <detail> element by default, but it can be suppressed by adding the following line in the runtime node's TRA file and restarting the node:

java.property.com.tibco.soapbt.spline.soapfaulttransformer.suppressstacktraceinsoapfault=true

The SOAP fault messages for a SOAP/HTTP reference binding timeout provides contextual information. When a timeout occurs on a partner call made from the application, the following additional information is provided in the SOAP Fault message, inside the 'faultstring' element:

The Binding (Endpoint) Name and Promoted Reference Name
Node name of the Reference Binding
Target URL that resulted in the timeout
Timeout Value specified and in effect
Time at which Timeout occurred
Service (Endpoint) Name and Promoted Service Name (where the call originated)
Host, Port and Endpoint URI of the Service Binding
Names of the Application, Node and Environment (of the Service Binding
Name of the Operation invoked
Host Address of the originating client (that sent the request to the Service Binding)

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