Unable to return client fault from service implementation

["William A. Nagy" <na...@watson.ibm.com>]

Hi guys,

I would like to propose an addition to the Apache SOAP deployment
descriptor, and the reason for that addition is as follows:

It is now impossible to have service implementation code initiate a
SOAPException(FAULT_CODE_CLIENT) from the server side (at least by the
standard Java provider.)  All InvocationTargetExceptions are being
caught, and their corresponding target exceptions are being rethrown
as SOAPException(FAULT_CODE_SERVER).  The SOAP v1.1 spec says:

-------------------------
The Client class of errors indicate that the message was incorrectly
formed or did not contain the appropriate information in order to
succeed. For example, the message could lack the proper authentication
or payment information. It is generally an indication that the message
should not be resent without change. See also section 4.4 for a
description of the SOAP Fault detail sub-element.

The Server class of errors indicate that the message could not be
processed for reasons not directly attributable to the contents of the
message itself but rather to the processing of the message. For
example, processing could include communicating with an upstream
processor, which didn't respond. The message may succeed at a later
point in time. See also section 4.4 for a description of the SOAP
Fault detail sub-element.
-------------------------

which to me clearly indicates that if the contents of the message are
invalid according to the syntax/semantics of the server, then a
SOAPException(FAULT_CODE_CLIENT) should be thrown.

Given that, the easiest fix would be to have the server check to see
if the target exception was an instance of a SOAPException, and then
to simply rethrow that SOAPException as is.  However, that would mean
that the service implementation needs to be aware of the fact that it
is running in a SOAP context.  I believe that a better solution would
be to allow users to specify a mapping between service implementation
faults and SOAP faults, so that they could indicate which
implementation faults should raise a SOAPException(FAULT_CODE_CLIENT).

To this end, I would propose the addition of a <clientCausedFault>
element to the deployment descriptor, so that for example, the stock
quote service deployment descriptor may look like the following:

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
             id="urn:xmltoday-delayed-quotes">
  <isd:provider type="java"
                scope="Application"
                methods="getQuote">
    <isd:java class="samples.stockquote.StockQuoteService"/>
    <isd:clientCausedFault>samples.stockquote.BadSymbolException</isd:clientCausedFault>
    <isd:clientCausedFault>samples.stockquote.AuthenticationException</isd:clientCausedFault>
  </isd:provider>
  <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>

In the case of the standard Java provider, the contents of the
clientCausedFault element(s) would be the fully qualified exception
name(s) that should be treated as client errors (and hence raise a
SOAPException(FAULT_CODE_CLIENT).)  With other providers, the contents
would refer to whatever is most appropriate for those contexts.

In the future, we could decide to further restrict the scope of the
clientCausedFault semantics by adding a method attribute to identify
which method(s) the mapping should apply to.

I already have an implementation of this which is fully backwards
compatible. (i.e. if you don't include clientCausedFault elements in
your deployment descriptors, then all service implementation
exceptions are thrown as they are now (as
SOAPException(FAULT_CODE_SERVER).

Comments?

-Bill