email article printer friendly

Generate SOAP Faults in JAX-RPC Handlers
Though generating errors in a JAX-RPC handler seems straightforward, it requires some work. Learn how to throw the correct exception
by Kevin Jones

Posted January 21, 2004

The Java API for XML-based Remote Procedure Calls (JAX-RPC) specification allows you to map Web service operations onto Java method calls through handlers, and you can use handlers to process SOAP headers for Web services applications. I discussed writing and configuring handlers for generic tasks previously (see "Write and Configure JAX-RPC Handlers," January 7, 2004). In another previous article I discussed writing JAX-RPC-based handlers for specific SOAP headers and some of the pitfalls you need to avoid (see "Process SOAP Headers in JAX-RPC Handlers," January 14, 2004). Handlers that manage SOAP headers will sometimes discover that those headers are wrong, and when that happens the handler has to generate a SOAP fault and return that fault back to the client. As you will see, this process is not quite as straightforward as it should be.

A JAX-RPC handler that is written to process SOAP headers is responsible for checking that those headers are valid. If it finds an invalid header, the handler should inform the runtime that processing of the current request should end and the runtime should be prepared to return a SOAP fault back to the sender of this message. It is the responsibility of the handler to set the SOAP fault in the return message. Imagine a SOAP message that looks something like you see in Listing 1, and then a handler that does this:

public boolean handleRequest(
  MessageContext messageContext)
{
  boolean bRet = true;
  SOAPMessageContext smc = 
    (SOAPMessageContext) 
    messageContext;
  SOAPMessage sm = 
    smc.getMessage();

  SOAPHeaderElement credentials = 
    null;
    // get the headers
    SOAPHeader sh = 
      sm.getSOAPHeader();
    // get the credentials header
    credentials = getCredentials(
      sh);
    // check that the credentials 
    // are valid
    if(checkCredentials(
      credentials) == false)
    {
      // signal an error
    }

    return true;
}

The detail of the handler is not important here; suffice it to say that the handler gets and processes the credentials header. The important point is what happens when the handler detects an error, for example an unknown user, or a mismatched user and password? This header is a must understand header, and there is no actor so this service must process the header. If it cannot, then the service must stop all further processing of the message and return a header fault.

There are several ways to stop processing the message. One way is to throw a JAXRPCException that signals that a run-time error has occurred in the processing of the message. The server's handler chain will produce a SOAP fault and send it back to the client.

For another way to return false, the server will stop processing the handleRequest() side of the chain and instead start processing the handleResponse() side of the handler chain. The handlers in the chain are responsible for producing the response SOAP message, either in this handleRequest() method or in one of the handleResponse() methods called in the chain. This alternative is intended for a scenario in which there is no error, but the handler wants to process the response itself.