Databases Reference
In-Depth Information
Defining faults
Unless returning a basic fault, that is, using a predefined fault code and no structured
content within the
soap:detail
, it is a good practice to define the fault as part of the
WSDL contract defining your service.
Faults are defined by adding the appropriate
fault
elements to the
operation
declarations. A fault has two attributes:
name
, which corresponds to the fault code
returned in the SOAP fault and
message
, which will contain additional information
about the fault and is returned within the
soap:detail
element.
For example, to define a fault for the
updateCreditCard
operation, we would just
add the following
fault
element to our definition, as shown in the following
code snippet:
<operationname="updateCreditCard">
<inputmessage="tns:updateCreditCard"/>
<outputmessage="tns:updateCreditCardResponse"/>
<fault name="tns:invalidCreditCard"
message="tns:invalidCreditCardFault "/>
</operation>
There is nothing to stop a service returning a fault which is undeclared in its service
contract. However, by declaring the fault, the service consumer has the opportunity
to handle the fault in an appropriate manner and by knowing the structure of the
fault detail, is able to process it in a more meaningful way.
Custom fault codes
Often it is desirable to define a custom fault, particularly for services which
may return a number of faults, as this can simplify fault handling for the service
consumer (as they can implement targeted fault handling mechanisms for each
type of fault).
SOAP 1.1 allows custom fault codes to be implemented through the use of the dot
notation, for example we could define a fault code of
client.invalidCreditCard
in
the SOAP namespace (
http://schemas.xmlsoap.org/soap/envelope/
). However,
this can result in namespace collision and interoperability issues so is not WS-I Basic
Profile-compliant and should be avoided.
Instead, custom fault codes should be defined within their own namespace. For
example, we have defined our
invalidCreditCard
fault code to be in the same
namespace as the actual
userManagement
service.
