by Michelle Cope
(April 2002)

We want to hear from you! Please send us your FEEDBACK.

The following article may contain actual software programs in source code form. This source code is made available for developers to use as needed, pursuant to the terms and conditions of this license.

Simple Object Access Protocol (SOAP) messages are used to exchange XML-encoded information in a distributed environment. SOAP messages are often used to implement a request/response messaging topology. For example, in a purchasing application for computer hardware, a client can send a SOAP encoded message to request the purchase of a keyboard to a SOAP HTTP server. The SOAP server responds with a SOAP message. If the request was successful then the response SOAP message contains an acknowledgement. Otherwise, it contains error information. According to the SOAP 1.1 specification, errors or status code information must be conveyed as SOAP faults in SOAP messages.  SOAP faults are generated in response to a request message that could not be handled. A SOAP message is usually not processed for two main reasons: the SOAP message did not comply with the SOAP specification or its application specific content was incomplete or incorrectly formed.  Section 4.4: SOAP Faults of the SOAP 1.1 Specification describes, in depth, the SOAP fault structure and the criteria for SOAP fault generation in a SOAP message. It is advisable that the reader familiarize themselves with this document before continuing. SOAP Messages with SOAP faults can be constructed and handled using JAXM. This article will describe how to use JAXM to send SOAP faults in SOAP messages over HTTP, with reference to the purchase application described.

In the purchasing application, a client issues a request to purchase a keyboard. The client must send details of the keyboard to the server, including the keyboard's category, number and price. Upon receiving a request, the SOAP server checks that the supplied details are correct and responds with a corresponding SOAP message. If the client sends the wrong category number, then an error has occurred. The SOAP server in response must  inform the client that an error occurred and hence, the request failed. According to the SOAP 1.1 specification, the SOAP server must send a SOAP message with a SOAP fault, and issue a HTTP 500 "Internal Server Error".  

The construction of a SOAP fault in a SOAP message is relatively simple. The SOAP server wants to generate a response SOAP message with the following structure and content:

<SOAP-ENV:Envelope xlmns:SOAP-ENV="http://schema.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
                <SOAP-ENV:faultcode>SOAP-ENV:Client</SOAP-ENV:faultcode>
                <SOAP-ENV:faultstring>Invalid input</SOAP-ENV:faultstring>
                <SOAP-ENV:Detail>
                            <INVALID_INPUT:invalidInputDetails xmlns:INVALID_INPUT="http://myfaultcodes.com/faults"/>
                            <Message> Invalid category number used </Message>
                            <ComputerPart>
                                <Category_Number> 124-342-343</Category_Number>
                                <Description>Keyboard</Description>
                                <Maker>    Dell    </Maker>
                                <Price>    50.32</Price>
                             </ComputerPart>
                            </INVALID_INPUT:invalidInputDetails>
                </SOAP-ENV:Detail>
      </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope

public SOAPMessage onMessage(SOAPMessage msg){

...
 
 	//Create a reply mesage from the msgFactory of JAXMServlet
        SOAPMessage replymsg = msgFactory.createMessage();
	SOAPPart sp = replymsg.getSOAPPart();
	SOAPEnvelope se = sp.getEnvelope();
	SOAPBody sb = se.getBody();


	//Assume that there is some logic to detect whether the category number is valid or not. 
	//Create the SoapFault element.
	SOAPFault sf = sb.addFault();
	sf.setFaultCode("SOAP-ENV:Client");
	sf.setFaultString("Invalid input");
        Detail dt = sf.addDetail();
        DetailEntry invalidElem = 
		dt.addDetailEntry(se.createName("invalidInputDetails", "INVALID_INPUT",
								 "http://myfaultcodes.com/faults"));
	SOAPElement messageElement = invalidElem.addChildElement(se.createName("Message"));
	messageElement.addTextNode("Invalid category number used");


        //Extract the ComputerPart element from request SOAP message, msg and add to reply SOAP message.
        SOAPPart reqsp = msg.getSOAPPart();
	SOAPEnvelope reqse = reqsp.getEnvelope();
        SOAPBody reqsb = reqse.getBody();

        SOAPElement errorComputerPart;

        //Retrieve a SOAPBody element from the request SOAPMessage with the name ComputerPart
        Iterator it = reqsb.getChildElements(reqse.createName("ComputerPart"));
	if(it.hasNext() & (errorComputerPart = (SOAPElement)it.next()) != null){
		invalidElem.addChildElement(errorComputerPart);
        }
        

        return replymsg;
...

}

...
        //GetHeaders is defined in javax.xml.messaging.JAXMServlet to retrieve mimeHeaders from HttpServletRequest
	//MimeHeaders include any SOAPAction, Content-Location, and Content-Type headers.
	MimeHeaders mimeHeaders = getHeaders(request);
        ServletInputStream sInputStream = request.getInputStream();

        //Create the SOAPMessage from the reply
        //msgFactory is a protected field of JAXMServlet
        SOAPMessage soapMessage = msgFactory.createMessage(mimeHeaders,sInputStream);

...

...

        SOAPMessage soapMessageReply = null;

	//Invoke this objects onMessage() 
        soapMessageReply = this.onMessage(soapMessage);

        if(soapMessageReply != null){
		if(soapMessageReply.saveRequired())
			soapMessageReply.saveChanges();
        //Check to see if presence of SOAPFault
                if(containsFault(soapMessageReply)){
			response.setStatus(500);
                }else response.setStatus(200);
...

...
 
        //Send the response back to the sender
        //by placing the mime headers into the response, and externalizing
        //the soapmessage onto the response object.
	//PutHeaders is a method from JAXMServlet.
        putHeaders(soapMessageReply.getMimeHeaders(), response);
        ServletOutputStream sOutputStream = response.getOutputStream();
	soapMessageReply.writeTo(sOutputStream);
	sOutputStream.flush();

...