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. |
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 returns 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>