Custom SOAP Fault messages

With Rational® Developer for System z®, you can specify SOAP Fault messages for problems that occur during the execution of business logic.

SOAP Fault messages in the SOAP body

A WSDL author can specify an XSD that defines the layout for the details of a problem for custom SOAP fault messages. Rational Developer for System z supports the generation of the PL/I structures, the mapping sessions, and metadata for each fault message defined for an operation. The custom SOAP Fault messages are carried in the SOAP Body, different from the SOAP Header Faults.

The SOAP Fault element has four sub-elements:

faultcode: A code for identifying the fault
faultstring: A human-readable explanation of why the Fault occurred
faultactor: The URI associated with the actor that caused the Fault on the message path
detail: Application-specific information about why the error occurs

<env:Body xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/”>
   <env:Fault>
      <env:faultcode>
         env:VersionMismatch | env:MustUnderstand | env:Client | env:Server
      </env:faultcode>
      <env:faultstring>
         // Human readable explanation of the fault
      </env:faultstring>
      <env:faultactor>
         // Who or what caused the fault
      </env:faultactor>
      <env:detail>
         // The contents of the detail element can be described using an XSD
         // Application-specific error information (such as wrong account number, 
or invalid request).
      </env:detail>
   </env:Fault>
</env:Body>

The following is a simplified sample WSDL file.

The operation MyOperation defines two possible SOAP fault messages, MyOperationException and MySystemException, that can be issued when the operation is invoked.
The MyOperationException fault message is intended to be used for reporting problems at the business-logic level, such as invalid account number or invalid request.
The MySystemException fault message is intended for reporting issues with the provision of the service itself, such as internal application error, if the corresponding fault data structure has been allocated in the message processing program (MPP).

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" …>
    <types>
        <schema …>
            <xs:element name="MyOperationRequest" type="p0:OperationRequestData" />
            <xs:complexType name="OperationRequestData">
                < … />
            </xs:complexType>
            <xs:element name="MyOperationResponse" type="p0:OperationResponseData" />	
            <xs:complexType name="OperationResponseData">
                < … />
            </xs:complexType>
            <xs:element name="MyOperationException" type="p0:OperationException" />
            <xs:complexType name="OperationException">
                <xs:sequence>
                    <xs:element name="op_error_code" type="xs:string" />
                    <xs:element name="op_trace_entry" type="xs:string"
                           minOccurs="0" maxOccurs="unbounded" />
                    </xs:sequence>
            </xs:complexType>
            <xs:element name="MySystemException" type="p0:SystemException" />
            <xs:complexType name="SystemException">
                <xs:sequence>
                    <xs:element name="sys_status_code" type="xs:string" />
                    <xs:element name="sys_status_message" type="xs:string" />
                    <xs:element name="sys_admin_email" type="xs:string" />
                    <xs:element name="sys_log_entry" type="xs:string"
                           minOccurs="0" maxOccurs="unbounded" />
                </xs:sequence>
            </xs:complexType>
        </schema>
    </types>
    <message name="MyOperationRequest">
        <part name="parameters" element="p0:MyOperationRequest" />
    </message>
    <message name="MyOperationResponse">
        <part name="parameters" element="p0:MyOperationResponse" />
    </message>
    <message name="MyOperationException">
        <part name="parameters" element="p0:MyOperationException" />
    </message>
    <message name="MySystemException">
        <part name="parameters" element="p0:MySystemException" />
    </message>
    <portType name="MyServicePortType">
  1     <operation name="MyOperation">
           <input message="p0:MyOperationRequest" />
           <output message="p0:MyOperationResponse" />
  2          <fault message="p0:MyOperationException" name="MyOperationException" />
  3          <fault message="p0:MySystemException" name="MyOperationException" />
        </operation>
    </portType>
    <binding name="MyServiceBinding" type="p0:MyServicePortType">
        <soap:binding style="document" 
            transport="http://schemas.xmlsoap.org/soap/http" />
            <operation name="MyOperation">
                <soap:operation 
                    soapAction="http://www.example.org/MyService/MyOperation" />
                <input>
                    <soap:body use="literal" />
                </input>
                <output>
                    <soap:body use="literal" />
                </output>
                <fault name="MyOperationException">
                    <soap:fault use="literal" name="MyOperationException" />
                </fault>
                <fault name="MySystemException">
                    <soap:fault use="literal" name="MySystemException" />
                </fault>
            </operation>
    </binding>
    <service name="MyService">
        <port binding="p0:MyServiceBinding" name="MyServicePort">
            <soap:address location="http://server:port/imssoap/services/MyService" />
        </port>
    </service>
</definitions>

For this WSDL file, the WSDL to PL/I mapping (WSDL2PLI) component would generate the PL/I structures, mapping sessions, and metadata for each fault message defined in the MyOperation operation. Multiple operations can share the same fault message. The IMS Connect XML adapter function would dynamically choose the converter package to use for the output message and include the appropriate Fault details for each operation.

The generated PL/I template includes the PL/I structure for each of the varying output:

 /*********************************************************************
  * REFER objects language structure "MyOperationException_ref" for r
  * esponse SOAP Fault language structure "MyOperationException" of b
  * inding operation(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 DCL 01 MyOperationException_ref UNALIGNED,
  /* @LIMIT MyOperationException.op_trace_entry
   */
  02 op_trace_entry_lim SIGNED FIXED BINARY(31);
  
 /*********************************************************************
  * POINTER language structure "MyOperationException_ptr" for respons
  * e SOAP Fault language structure "MyOperationException" of binding
  *  operation(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 /* @POINTER MyOperationException
  */
 DCL 01 MyOperationException_ptr POINTER;
  
 /*********************************************************************
  * Response SOAP Fault language structure "MyOperationException" for
  *  binding operation(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 /* @XPATH Fault/Detail/MyOperationException
  */
 DCL 01 MyOperationException UNALIGNED BASED(MyOperationException_ptr),
  /* @XPATH Fault/faultcode
   */
  02 faultcode CHAR(64) VARYING,
  /* @XPATH Fault/faultstring
   */
  02 faultstring CHAR(64) VARYING,
  /* @XPATH Fault/faultactor
   */
  02 faultactor CHAR(64) VARYING,
  /* @LIMIT MyOperationException.op_trace_entry
   */
  02 op_trace_entry_lim SIGNED FIXED BINARY(31),
  /* @XPATH Fault/Detail/MyOperationException/op_error_code
   */
  02 op_error_code CHAR(64) VARYING,
  /* @COUNT MyOperationException.op_trace_entry
   */
  02 op_trace_entry_cnt SIGNED FIXED BINARY(31),
  /* @XPATH Fault/Detail/MyOperationException/op_trace_entry
   */
  02 op_trace_entry (MyOperationException_ref.op_trace_entry_lim REFER (
 op_trace_entry_lim)) CHAR(64) VARYING; 

 /*********************************************************************
  * REFER objects language structure "MySystemException_ref" for resp
  * onse SOAP Fault language structure "MySystemException" of binding
  *  operation(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 DCL 01 MySystemException_ref UNALIGNED,
  /* @LIMIT MySystemException.sys_log_entry
   */
  02 sys_log_entry_lim SIGNED FIXED BINARY(31);
  
 /*********************************************************************
  * POINTER language structure "MySystemException_ptr" for response S
  * OAP Fault language structure "MySystemException" of binding opera
  * tion(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 /* @POINTER MySystemException
  */
 DCL 01 MySystemException_ptr POINTER;
  
 /*********************************************************************
  * Response SOAP Fault language structure "MySystemException" for bi
  * nding operation(s) "MyOperation, MySecondOperation".
  ********************************************************************/
 /* @XPATH Fault/Detail/MySystemException
  */
 DCL 01 MySystemException UNALIGNED BASED(MySystemException_ptr),
  /* @XPATH Fault/faultcode
   */
  02 faultcode CHAR(64) VARYING,
  /* @XPATH Fault/faultstring
   */
  02 faultstring CHAR(64) VARYING,
  /* @XPATH Fault/faultactor
   */
  02 faultactor CHAR(64) VARYING,
  /* @LIMIT MySystemException.sys_log_entry
   */
  02 sys_log_entry_lim SIGNED FIXED BINARY(31),
  /* @XPATH Fault/Detail/MySystemException/sys_status_code
   */
  02 sys_status_code CHAR(64) VARYING,
  /* @XPATH Fault/Detail/MySystemException/sys_status_message
   */
  02 sys_status_message CHAR(64) VARYING,
  /* @XPATH Fault/Detail/MySystemException/sys_admin_email
   */
  02 sys_admin_email CHAR(64) VARYING,
  /* @COUNT MySystemException.sys_log_entry
   */
  02 sys_log_entry_cnt SIGNED FIXED BINARY(31),
  /* @XPATH Fault/Detail/MySystemException/sys_log_entry
   */
  02 sys_log_entry (MySystemException_ref.sys_log_entry_lim REFER (sys_l
 og_entry_lim)) CHAR(64) VARYING;

For more information about the support for SOAP Fault messages and related restrictions, see the Rational Developer for System z information center.