Oracle® Fusion Middleware
Part 19. Fault Handler Filters

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 API Gateway returns a very basic SOAP Fault to the client when a message filter has failed. You can add the SOAP Fault processor 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.

The following configuration options are available in this section:

SOAP Version:

You can 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 selected, an XSL stylesheet is run over the SOAP Fault to indent nested XML elements. The indented SOAP Fault is returned to the client.

The following configuration options are available in this section:

Show Detailed Explanation of Fault:

If this option is selected, a detailed explanation of the SOAP Fault is returned in the fault message. This makes it possible to suppress the reason for the exception in a tightly locked down system (the reason is displayed as message blocked in the SOAP Fault).

Show Filter Execution Path

When this option is selected, the API Gateway returns 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 is given (pass or fail). 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 selected, the API Gateway returns 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 selecting this option, the message attributes present at the time the SOAP Fault was generated are returned to the client. Each message attribute forms the content of a <fault:attribute> element, as shown 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>

You can use the following approaches to create customized SOAP faults:

Using the Generic Error Filter

Instead of using the SOAP Fault filter, you can use the Generic Error filter to transform the SOAP fault message returned by applying an XSLT stylesheet. The Generic Error filter examines the incoming message and infers the type of message to be returned (for example, JSON or SOAP). For more details, see the Generic Error topic.

Using the Set Message Filter

You can create customized SOAP Faults using the Set Message filter with the SOAP Fault filter. The Set Message filter can change the contents of the message body to any arbitrary content. When an exception occurs in a policy, you can 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:

This example first creates a very simple policy called Main Policy. This policy ensures the size of incoming messages is between 100 and 1000 bytes. Messages in this range are echoed back to the client.

Step 2: Create the Fault Policy

Next, create a second policy called Fault Circuit. This policy uses 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.

Step 3: Create a shortcut to the Fault Policy

Add a Policy Shortcut filter to the Main Policy and configure it to refer to the Fault Circuit. Do not connect this filter to the policy. Instead, right-click the filter, and select the Set as Fault Handler menu option. The Main Policy is displayed as follows:

So how does it work? Assume a 2000-byte message is received by the API Gateway and is passed to the Main Policy for processing. The message is parsed by the HTTP Parser filter, and the size of the message is checked by the Message Size filter. Because the message is greater than the size constraints set by this filter, and because there is no failure path configured for this filter, an exception is thrown.

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

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