This
is a revised SOAP Fault Proposal, originally proposed by Christine.
----------------------------------
Handling
Failures.
----------------------------------
SOAP
Fault MUST be used only when an error or
errors occurred outside DSML. For example, when processing
between
SOAP Server to a DSML server/gateway.SOAP
Fault should not be used to communicate failures
inside
the DSML system. errorResponse
and LDAP errors are the examples of failure originating from within DSML.
When
SOAP is used to transport DSML document, there are three potential failure
points:
1) Communication
between SOAP and DSML. For example DSML server/gateway is not responding
to SOAP server.
In
this case, SOAP server should return SOAP Fault.
(Please
note: SOAP and DSML can be implemented in the same server or component.)
Example:
<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Fatal
error: DSML gateway is not responding</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
In
addition to this scenario, SOAP client may transmit an invalid SOAP message,
in this case, SOAP server responds with SOAP Fault.
This
specific scenario is outside the scope of the specification. Please consult
the latest SOAP specification for this matter.
Example:
<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>Client.ERR_SOAP</faultcode>
<faultstring>
Check SOAPAction header..."http://test-uri"
'Body' element expected
Fatal error:not valid SOAP message
</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
2) As
it mentions in the DSMLv2 specification, a client may produce a request
document that is syntactically incorrect, i.e. does not conform to dsmlEnvelopeRequestschema.
In this case the DSMLv2-based server still produces a response document,
and the response document should be included as part of SOAP Body.
Other scenario could be where a
DSML gateway can not establish a connection to the target LDAP server.
Example:
<se:Envelopexmlns:se='http://schemas.xmlsoap.org/soap/envelope/'>
<se:Header/>
<se:Body>
<dsml:dsmlEnvelopeResponsexmlns:dsml="urn:oasis-open:dsml:2”>
<dsml:errorResponse
type="couldNotConnect">
<dsml:message>Cannot
connect to a DSML server</dsml:message>
</dsml:errorResponse>
</dsml:dsmlEnvelopeResponse>
</se:Body>
</se:Envelope>
3)
A failure or failures may occur during LDAP operations. In DSMLv2, it is
expressed in theLDAPResult with a ResultCode
corresponding
to any LDAPErrorCode other than: 'success',
'compareFalse' or 'compareTrue'.
As with (2), DSMLv2 response document should be included in SOAP body
Example:
<se:Envelopexmlns:se='http://schemas.xmlsoap.org/soap/envelope/'>
<se:Header/>
<se:Body>
<dsml:dsmlEnvelopeResponsexmlns:dsml="urn:oasis-open:dsml:2"
xmlns:batch="urn:oasis-open:dsml:2:batch">
<dsml:modifyResponse>
<resultCode
code="53" descr="unwillingToPerform"/>
<errorMessage>System
Attribute may not be modified</errorMessage>
</dsml:modifyResponse>
<dsml:addResponse>
<resultCode
code="0"/>
</dsml:addResponse>
<dsml:naddResponse>
<resultCode
code="0" descr="success"/>
<control>...</control>
<control>...</control>
</dsml:addResponse>
</dsml:dsmlEnvelopeResponse>
</se:Body>
</se:Envelope>