JAX-WS: A @SchemaValidation custom handler to alter framework SOAP faults

A few days ago I blogged about suppressing the SOAP fault detail Java stack trace on WebLogic Server when using the JAX-WS @SchemaValidation annotation for your web services.

One of the problems with the @SchemaValidation annotation is dependent on the error in your incoming SOAP payload, you may get all sorts of potential errors returned in a SOAP fault. In some cases it might be useful or a requirement that a generic SOAP fault message be sent back in this case. How to do this?

As usual I'm documenting my research and solution here for my own purposes, but hopefully helpful to others. Your mileage may vary.

Consider the following JAX-WS endpoint:

@WebService
@SchemaValidation
public class WebServiceClass {

  @WebMethod
  public MyResponse lodgeReport(@WebParam MyRequest request)
    throws GenericSoapFault {
    // do some stuff
  }
}

(I've clipped a lot of the detail from above to focus on the specifics)

Notice the @SchemaValidation annotation. By default this will enforce that the incoming SOAP payload conforms to the XML schema for the operation. For instance an invalid payload may throw the following error:

   
      
         
            S:Receiver
         
         
            org.xml.sax.SAXParseException: cvc-datatype-valid.1.2.1: '?' is not a valid value for 'dateTime'.
         
      
   

Note the reason/text part of the SOAP fault may be virtually any SAXParseException error message depending on the error discovered in the incoming SOAP payload.

We can however override the @SchemaValidation annotation to specify the actual error handler. We change the endpoint code as such:

@WebService
@SchemaValidation(handler = SchemaValidationErrorHandler.class)
public class WebServiceClass {

  @WebMethod
  public MyResponse lodgeReport(@WebParam MyRequest request)
    throws GenericSoapFault {
    // do some stuff
  }
}

Note the handler attribute specifying the SchemaValidationErrorHandler class for the @SchemaValidation annotation. In turn the SchemaValidationErrorHandler is implemented as follows:

import com.sun.xml.ws.developer.ValidationErrorHandler;
import org.xml.sax.SAXParseException;

public class SchemaValidationErrorHandler extends ValidationErrorHandler {

  public void warning(SAXParseException exception) { }

  public void error(SAXParseException exception) {  }

  public void fatalError(SAXParseException exception) { }
}

Any warning, error or fatal error for the @SchemaValidation will now be passed through to the methods above. Remembering our goal to supplement a custom error message for any of the errors above (well, maybe not warning, we'll ignore warnings), we'd like to return our own SOAP fault. Unfortunately we can't do that from the handler, we need to pass the error back to the endpoint method. This is done by using the com.sun.xml.ws.api.message.Packet that is available from the ValidationErrorHandler super class. In essence we can change our handler class as follows:

public class SchemaValidationErrorHandler extends ValidationErrorHandler {

  public static final String WARNING = "SchemaValidationWarning";
  public static final String ERROR = "SchemaValidationError";
  public static final String FATAL_ERROR = "SchemaValidationFatalError";

  public void warning(SAXParseException exception) {
    packet.invocationProperties.put(WARNING, exception);
  }

  public void error(SAXParseException exception) {
    packet.invocationProperties.put(ERROR, exception);
  }

  public void fatalError(SAXParseException exception) {
    packet.invocationProperties.put(FATAL_ERROR, exception);
  }
}

I can't for the life of me find the JavaDoc for the Packet class, but what I believe it does is wrap the overall web service message context, and we can drop properties into the packet to be retrieved elsewhere by our JAX-WS solution , specifically our end point.

Returning to the JAX-WS endpoint we need to inject the web service message context, and then we can retrieve each of the individual errors from the SchemaValidationErrorHandler above:

@WebService
@SchemaValidation(handler = SchemaValidationErrorHandler.class)
public class WebServiceClass {

  @Resource
  WebServiceContext wsContext;

  @WebMethod
  public MyResponse lodgeReport(@WebParam MyRequest request)
    throws GenericSoapFault {
    
    MessageContext messageContext = wsContext.getMessageContext();
    // We'll ignore warnings
    // SAXParseException warningException = (SAXParseException)messageContext.get(SchemaValidationErrorHandler.WARNING);
    SAXParseException errorException = (SAXParseException)messageContext.get(SchemaValidationErrorHandler.ERROR);
    SAXParseException fatalErrorException =       (SAXParseException)messageContext.get(SchemaValidationErrorHandler.FATAL_ERROR);

    String errorMessage = null;

    if (errorException != null)
      errorMessage = errorException.getMessage();
    else if (fatalErrorException != null)
      errorMessage = fatalErrorException.getMessage();


     if (errorMessage != null)
       throw new GenericSoapFault(errorMessage);

     // Otherwise process the request
  }
}

Note the @Resource annotation in the class injecting the web service context, then within our endpoint method fetching the MessageContext from the wsContext, which gives us the ability to retrieve the properties we inserted in the SchemaValidationErrorHandler class.

As per the solution above, instead of just checking if the errorMessage is null and passing that to the GenericSoapFault, you could instead replace the SAXParseException with a more generic error message.