SOAP Faults

Before moving on to the topic, SOAP faults, I will simple make you remind what actually SOAP is. SOAP which is known as the Simple Object Access Protocol is an XML-based messaging protocol which is used to exchange information between entities.

SOAP nodes can be considered as SOAP processing capable units which are used to forward or retrieve soap messages.The node that sends the SOAP message is known as the SOAP sender while the node that receives become the SOAP receiver.

SOAP sender and receiver

The SOAP Message includes the information that in passed between the two SOAP nodes.A SOAP messages can be discussed under SOAP envelope, SOAP header, SOAP body and SOAP faults.

SOAP message structure

SOAP Envelope enclose all the XML elements by making the underline message to be expose to outside as SOAP. SOAP headers can contain one or more soap header blocks which targets the SOAP receiver node. SOAP body also contains such soap blocks. Then comes the SOAP faults, our main discussion. 😄

When a SOAP node fails to process a SOAP message, a SOAP fault is created.The following piece of text shows a simple SOAP fault.

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Client</faultcode>
            <faultstring>An Error Occured</faultstring>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP fault code element, provides a way to identify a soap fault in an algorithmic way. That means a SOAP fault code value should always be a qualified name. The namespace identifier for the fault-code is http://schemas.xmlsoap.org/soap/envelope/ and the following are the set of valid fault codes defined under the SOAP11 documentation.

VersionMismatch
    Use when the SOAP processing party finds an invalid namespace for SOAP envelope element.
MustUnderstand
    Use when the immediate child element of the Header Element with the must understand set to "1" and not understood.
Client
    Use when the SOAP message sends by the client is incorrectly formed.
Server
    Use when the sever cannot process the soap message due to some reasons, although the client has send the message accurately.

Fault string is used the provide information on the nature of the error occurred.Unlike the fault code, fault string is not used in algorithmic processing as it is set up to explain the nature of the soap fault to be understood by the human.

Fault actor is used a elaborate on who causes the fault. That means it indicates the fault source.

Detail element in the fault body carries information on the application specific error information related to soap body. It MUST NOT be used to carry such error elements connected to the header entries.Such detailed error information should be handled by the header entries.

Simply if you see a soap fault without detail element in the Fault body it simple says that the the fault is not related the processing of the SOAP body.

javax.xml.soap is a simple library which we can use to create SOAP messages.

Now let’s try to make a simple SOAP fault and return it as a String.

public static String createSOAPFault(String faultString, String faultcode){
    SOAPMessage soapMsg =  null;
    try {
        MessageFactory factory = MessageFactory.newInstance();
        soapMsg = factory.createMessage();
        SOAPPart part = soapMsg.getSOAPPart();

        SOAPEnvelope envelope = part.getEnvelope();
        SOAPHeader header = envelope.getHeader();
        SOAPBody body = envelope.getBody();
        SOAPFault fault = body.addFault();
        fault.setFaultString(faultString);
        fault.setFaultCode(new QName("http://schemas.xmlsoap.org/soap/envelope/", faultcode));

    } catch (SOAPException e){
        String err = "SOAP Exception when creating SOAP fault";
        log.error(err);
    }
    return soapMessageToString(soapMsg);
}
public static String soapMessageToString(SOAPMessage message)
{
    String result = null;
    if (message != null)
    {
        ByteArrayOutputStream baos = null;
        try
        {
            baos = new ByteArrayOutputStream();
            message.writeTo(baos);
            result = baos.toString();
        }
        catch (Exception e)
        {
        }
        finally
        {
            if (baos != null)
            {
                try
                {
                    baos.close();
                }
                catch (IOException ioe)
                {
                }
            }
        }
    }
    return result;

I believe you got a simple idea of what a SOAP fault is . 🆒