Glen Mazza's Weblog

« Tracing SOAP calls... | Main | Using MTOM and Apach... »

https://web-gmazza.rhcloud.com/blog/date/20170514 Sunday May 14, 2017

Sending and processing SOAP faults in web service calls

Following a useful article from Oracle on SOAP faults, this entry expands my intro DoubleIt web service to handle both "modeled" faults (those defined in the WSDL via wsdl:fault elements) and "unmodeled" ones (generally, runtime exceptions that get processed as SOAPFaultExceptions by the SOAP client.) The finished source code can be obtained from GitHub by using either the download ZIP button or git clone -v git://github.com/gmazza/blog-samples.git command.

Here, the DoubleIt web service provider has been adjusted to throw separate WSDL-defined exceptions if the client attempts to double odd numbers or the number 316. As these faults are WSDL-defined, the CXF WSDL-to-Java code generation tool activated by the service's pom.xml generates specific exception classes (DoubleOddNumberFault and DoubleNumber316Fault) for these that can be thrown by the WSP and caught by the SOAP client. Further, attempts to double 428 will throw a non-WSDL-defined runtime exception to show how the client receiving a generic SOAPFaultException.

WSDL changes: The modified WSDL contains two new wsdl:messages for the new faults which you can see subsequently referenced in the wsdl:portType and wsdl:binding sections. It's important to note each wsdl:message needs to have a distinct value for its element (here, DoubleOddFault and Double316Fault defined in the wsdl:types section), even though those two elements have identical contents. This is because the SOAP client uses the element name to determine the type of exception being thrown. (As you can see in the second and third SOAP responses at the bottom, the only difference between the two exceptions is the name of this element.) If you attempt to reuse the same element, results will be shaky. Also note that the wsdl:fault definitions in the portType and binding sections are tied together via their name attributes.

Web service provider: The WSP has been updated to throw the two WSDL-defined faults as well as the RuntimeException for disallowed values.

The WAR submodule's cxf-servlet.xml also has a commented-out faultStackTraceEnabled setting that, if activated, results in the server's Java exception stack trace being sent to the client within every SOAP fault returned. It is seldom desired to leak internal data from the WSP to the SOAP client in such manner (and also makes for rather bloated SOAP responses), but the option is available and perhaps useful in some cases where the service and client are being maintained by the same team.

SOAP Client processing faults: Four calls are made, an acceptable call to double 22 and three other calls that will activate exceptions.

Review of SOAP requests and responses for each of the calls: Running the WSP and activating the client as explained in the original tutorial provides the following output from the client:

The number 22 doubled is 44
Odd number fault: Don't double odd numbers!; basic fault text: 11 is an odd number
316 Fault: Don't double 316!; basic fault text: Attempt was made to double 316
SOAPFaultException: Ha ha!  Didn't tell you 428 can't be doubled either!

Below shows the first SOAP request (the other three differ only by the number being doubled) as well as the SOAP responses for each of the four calls.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:DoubleIt xmlns:ns2="http://www.example.org/schema/DoubleIt">
            <numberToDouble>22</numberToDouble>
        </ns2:DoubleIt>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:DoubleItResponse xmlns:ns2="http://www.example.org/schema/DoubleIt">
            <doubledNumber>44</doubledNumber>
        </ns2:DoubleItResponse>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Don't double odd numbers!</faultstring>
            <detail>
                <ns2:DoubleOddFault xmlns:ns2="http://www.example.org/schema/DoubleIt">
                    <errorDetails>11 is an odd number</errorDetails>
                </ns2:DoubleOddFault>
            </detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Don't double 316!</faultstring>
            <detail>
                <ns2:Double316Fault xmlns:ns2="http://www.example.org/schema/DoubleIt">
                    <errorDetails>Attempt was made to double 316</errorDetails>
                </ns2:Double316Fault>
            </detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Ha ha! Didn't tell you 428 can't be doubled either!</faultstring>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed

Valid HTML! Valid CSS!

This is a personal weblog, I do not speak for my employer.