Fault Handling

A fault can come from any of the following sources:

• A partner service returns an error message. In this case, the fault name and data are described in the WSDL definition.

• The SOA runtime product returns an error, as when a partner service is unavailable or a network fails. In this case, the fault name and data are described (at best) in product documentation.

• The BPEL engine reports a runtime problem. Again, check your product documentation. You also can review the BPEL specification, which lists the faults (called standard faults) that are thrown by any standards-compliant BPEL engine.

• Your BPEL process issues a throw activity in response to a business problem. In this case, your company is defining the fault name and data and should be keeping a record of those definitions so they can be reused in other processes.

The primary purpose of fault handling is to minimize the effect of an error so that the usual work of the business can continue.

After a fault occurs in a given scope, the scope has failed and is not available for compensation by a parent scope. The BPEL engine selects a scope-specific fault handler, terminates other handlers and activities in the current scope, terminates each descendant scope that is still running, and runs the fault handler.

The fault handler can respond in various ways and often issues a compensate activity to invoke compensation handlers in nested scopes that completed successfully. If, on completion, the fault handler issues the rethrow activity, processing continues in a fault handler in the parent scope. The parent scope has failed and is not available for compensation by its parent scope. If the fault handler does not issue the rethrow activity, normal processing resumes either in the parent scope or (if the faulting scope was nested directly in the process) at the top level of the process.

If a fault reaches the top level of the process or originates there, the BPEL engine terminates the process and informs the SOA runtime product of the failure.

Selection at Run Time

A fault handler is composed of a catch or optional catchAll element, with embedded activities. The outline shown in Listing 7.5 has three fault handlers.

Listing 7.5: Fault handler outline

 <faultHandlers>    <catch faultName="oneFault"       faultVariable="oneVariable"       faultElement="getDMVRecordElement">       <empty/>    </catch>    <catch faultName="twoFault">       <empty/>    </catch>    <catch       faultVariable="threeVariable"       faultMessageType="getDMVRecordRequest">       <empty/>    </catch>    <catchAll>       <empty/>    </catchAll> </faultHandlers> 

Each fault handler has selection criteria, which include (optionally) the fault name and the type of data.

If you specify a variable name, the BPEL process implicitly declares a variable that receives data and is local to the fault handler. The declaration is based on either an XML Schema element or a WSDL message type.

The BPEL engine selects the fault handler whose selection criteria most closely mirror the fault. Let's wade into a description of "most closely."

If the fault has a name but no data, the BPEL engine selects the fault handler whose selection criteria match exactly. If no such fault handler is available, the engine selects the catchAll handler. If the fault has data, the BPEL engine selects the fault handler whose selection criteria match exactly; or (if necessary) match nearly, with an exact match on fault name as long as no data type is specified in the selection criteria; or (if necessary) match nearly, when no fault name is specified in the selection criteria but an exact match is found on the data type. If no fault handlers conform to those rules, the engine selects the catchAll handler.

Here are some results when the fault handlers for a given scope are as shown in the preceding figure:

• If the scope throws a fault named oneFault and the fault has no data, the BPEL engine selects the catchAll handler.

• If the scope throws a fault named twoFault, the BPEL engine selects the fault handler named twoFault regardless of whether the fault has data.

• If the scope throws a fault named unknown and the fault has data that corresponds with a message of type getDMVRecordRequest, the BPEL engine selects the third fault handler.

If any fault handler issues a rethrow activity, the data presented to the fault handler of the parent scope is identical to the original data, even if the original fault handler changed the data or did not include a variable to accept the data.

If you don't include a catchAll handler in a given scope or at the process level, the BPEL engine provides the following default:

 <catchAll>    <sequence>       <compensate/>       <rethrow/>    </sequence> </catchAll> 

The Inner Life of a Fault Handler

A fault handler can be quite complex, with internal scopes, and a fault can occur in a fault handler. Here are a few details, which you can skip if your head hurts:

• The top level of a fault handler (for example, the handler called one) cannot include a fault, compensation, or termination handler; and no default handlers are available at that level.

• A scope nested directly in the fault handler cannot include a compensation handler. This second restriction is caused by the first, as you have no way to invoke a compensation handler except from a fault, compensation, or termination handler in a parent scope.

• A fault in a fault handler is always thrown to a parent scope, regardless of whether you issue a rethrow activity.

• A fault in a fault handler is ultimately thrown to the process - specifically, to the parent scope of the scope that contains the fault handler (in our case, the fault handler called one).

Exiting in Response to a Fault

Two attributes of the process element affect fault handling.

First, if you set the exitOnStandardFault attribute to yes rather than to its default no value, a BPEL standard fault exits the process without causing invocation of a fault or termination handler. The only standard fault that is unaffected by this attribute is the concurrency-related fault bpel:joinFailure.

Second, thettribute suppressJoinFailure affects how the process responds to the standard fault bpel:joinFailure. The details are later in this chapter, in the section on advanced concurrency.