SOAP Fault

Contents

Overview

In cases where a typical SOAP transaction fails, a SOAP Fault can be used to convey error information to the SOAP client. The following message shows the format of a SOAP Fault: 

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>Receiver</env:Value>
    <env:Subcode>
     <env:Value>policy failed</env:Value>
    </env:Subcode>
   </env:Code>
   <env:Detail xmlns:oraclefault="http://www.oracle.com/soapfaults" 
               oraclefault:type="exception" type="exception"/>
  </env:Fault>
 </env:Body>
</env:Envelope>

By default, the Enterprise Gateway returns a very basic SOAP Fault to the client when a message filter has failed. The SOAP Fault processor can be added to a policy to return more complicated error information to the client.

For security reasons, it is good practice to return as little information as possible to the client. However, for diagnostic reasons, it is useful to return as much information to the client as possible. Using the SOAP Fault processor, administrators have the flexibility to configure just how much information to return to clients, depending on their individual requirements.

SOAP Fault Format

The following configuration options are available in this section:

SOAP Version:
It is possible to send either a SOAP Fault 1.1 or 1.2 response to the client. Select the appropriate version using the radio buttons provided.

Fault Namespace:
Select the default namespace to use in SOAP Faults, or enter a new one if necessary.

Indent SOAP Fault:
If this option is checked, an XSL stylesheet will be run over the SOAP Fault in order to indent nested XML elements. The indented SOAP Fault will be returned to the client.

SOAP Fault Contents

The following configuration options are available in this section:

Show Detailed Explanation of Fault:
If this option is checked, a detailed explanation of the SOAP Fault will be returned within the fault message. This makes it possible to suppress the reason for the exception in a tightly locked down system, i.e. the reason will simply appear as "message blocked" in the SOAP Fault.

Show Filter Execution Path
When this option is checked, the Enterprise Gateway will return a SOAP Fault containing the list of filters run on the message before the error occurred. For each filter listed in the SOAP Fault, the status (i.e. "pass" of "fail") is given. The following message shows a filter execution path returned in a SOAP Fault: 

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>Receiver</env:Value>
    <env:Subcode>
     <env:Value>policy failed</env:Value>
    </env:Subcode>
   </env:Code>
   <env:Detail xmlns:oraclefault="http://www.oracle.com/soapfaults" 
   oraclefault:type="exception" type="exception">
    <oraclefault:path>
     <oraclefault:visit node="HTTP Parser" status="Pass"></oraclefault:visit>
     <oraclefault:visit node="/services" status="Fail"></oraclefault:visit>
     <oraclefault:visit node="/status" status="Fail"></oraclefault:visit>
    </oraclefault:path>
   </env:Detail>
  </env:Fault>
 </env:Body>
</env:Envelope>

Show Stack Trace
If this option is checked, the Enterprise Gateway will return the Java stack trace for the error to the client. This option should only be enabled under instructions from the Oracle Support Team.

Show Current Message Attributes
By checking this option, the message attributes present at the time the SOAP Fault was generated will be returned to the client. Each message attribute will form the content of a <fault:attribute> element, as illustrated in the following example: 

<fault:attributes>
  <fault:attribute name="circuit.failure.reason" value="null">
  <fault:attribute name="circuit.lastProcessor" value="HTTP Digest">
  <fault:attribute name="http.request.clientaddr" value="/127.0.0.1:4147">
  <fault:attribute name="http.response.status" value="401">
  <fault:attribute name="http.request.uri" value="/authn">
  <fault:attribute name="http.request.verb" value="POST">
  <fault:attribute name="http.response.info" value="Authentication Required">
  <fault:attribute name="circuit.name" value="Digest AuthN">
</fault:attributes>

Customized SOAP Faults

It is possible to create customized SOAP Faults using the Set Message filter. The Set Message filter can change the contents of the message body to any arbitrary content. When an exception occurs in a policy, it is possible to use this filter to customize the body of the SOAP fault. The following example demonstrates how to generate customized SOAP faults and return them to the client.

Step 1: Create the Top-level Policy:
We will first create a very simple policy called "Main Circuit". This policy will ensure the size of incoming messages is between 100 and 1000 bytes. Messages within this range will be echoed back to the client.

Main Circuit

Main Circuit

Step 2: Create the Fault Policy
Next, create a second policy called "Fault Circuit". This policy will use the Set Message filter to customize the body of the SOAP fault. When configuring this filter, enter the contents of the customized SOAP fault that you want to return to clients in the text area provided.

Fault Circuit

Fault Circuit

Step 3: Create a shortcut to the Fault Policy
Add a Policy Shortcut filter to the "Main Circuit" and configure it to refer to the "Fault Circuit". Do not connect this filter to the policy. Instead, right-click on the filter and select the Set as Fault Handler menu option. The "Main Circuit" now appears as follows:

Main Circuit with Fault Handler

Main Circuit with Fault Handler

So how does it work? Let's assume a 2000-byte message is received by the Enterprise Gateway and is passed to the "Main Circuit" for processing. The message is parsed by the HTTP Parser filter and then the size of the message is checked by the Message Size filter. Since the message is greater than the size constraints set by this filter, and since there is no failure path configured for this filter, an exception will be thrown.

When an exception is thrown in a policy, it is handled by the designated Fault Handler, if one is present. In the "Main Circuit", we have set a Policy Shortcut filter to be the fault handler. This filter delegates to the "Fault Circuit", meaning that when an exception occurs, "Main Circuit" will invoke (or delegate to) the "Fault Circuit".

The "Fault Circuit" consists of 2 filters, which play the following roles:

  1. Set Message:
    This filter is used to set the body of the message to the contents of the customized SOAP fault.
  2. Reflect:
    Once the SOAP fault has been set to the message body, it will be returned to the client using the Reflect filter.