Generating SOAP Faults from a Web Service

For web services that use SOAP as their message format, the proper way to inform a client about errors encountered while processing an invocation message is to return a SOAP fault. A SOAP fault element may contain one or more detail objects describing the problem encountered.

In a WebLogic Workshop web service, there are three ways for you to create a SOAP fault and return it to the client:

You can construct and throw an exception of type com.bea.jws.SoapFaultException using an XMLBeans type that represents the entire SOAP fault element. This approach gives you full control over the content of the fault. The XMLBeans type that you use depends on which fault type (from the WSDL file) you want to throw.

You can construct an exception of type com.bea.jws.SoapFaultException and add fault detail objects as desired. This provides a simple way to build a fault that has complex types in the fault detail.

You can construct and throw an exception of type javax.xml.rpc.soap.SOAPFaultException. This approach is provided for compatibility purposes. This exception type is specific to the SOAP 1.1 envelope and can only be thrown while processing a SOAP 1.1 request. You can determine the SOAP version of the current request from within a web service method by calling the getProtocol() method of com.bea.control.JwsContext.

SOAP Faults, Details and XMLBeans

The WSDL file for a web service specifies the types of SOAP faults that may be returned by the web service, including the particular object types that may be included in the SOAP fault detail. WSDL files you receive from external sources and implement as WebLogic Workshop web services may include SOAP fault definitions.

The easiest way to handle SOAP fault detail types is with XMLBeans. If you add a WSDL file to the Schemas project of your application, all of the types defined in the WSDL's schema, including any SOAP fault detail types, will be compiled into XMLBeans. You can use the generated XMLBeans types to create SOAP fault detail objects and use the com.bea.jws.SOAPFaultException API to include the detail objects in SOAP faults you throw.