8 Fault Handling

8.1 Use Case for Fault Handling

This chapter uses an example of a credit rating service returning a negative credit message instead of a credit rating number. You also learn how to add a fault handler to a BPEL process to handle the message.

8.2 Defining a Fault Handler

Fault handlers define how the BPEL process responds when the Web services return data other than what is normally expected (for example, returning an error message instead of a number). An example of a fault handler is where the Web service normally returns a credit rating number, but instead returns a negative credit message.

Figure 8-1 shows how a fault handler sets the credit rating variable at -1000.

Figure 8-1 Fault Handling

Description of the illustration bpmdg002.gif

The following code segment defines the fault handler for this operation:

<faultHandlers>
     <catch faultName="services:NegativeCredit" faultVariable="crError">
      <assign name="crin">
         <copy>
           <from expression="-1000">
           </from>
           <to variable="input" part="payload"
               query="/autoloan:loanApplication/autoloan:creditRating"/>
         </copy>
       </assign>
     </catch>
</faultHandlers>

The faultHandlers tag contains the fault handling code. Within the fault handler is a catch activity, which defines the fault name and variable, and the copy instruction that sets the creditRating variable to -1000.

When you select Web services for the BPEL process, determine the possible faults that may be returned and set up a fault handler for each one.

8.3 BPEL Standard Faults

The Business Process Execution Language for Web Services Specification defines the following standard faults in the namespace of http://schemas.xmlsoap.org/ws/2003/03/business-process/:

• selectionFailure

• conflictingReceive

• conflictingRequest

• mismatchedAssignmentFailure

• joinFailure

• forcedTermination

• correlationViolation

• uninitializedVariable

• repeatedCompensation

• invalidReply

Standard faults are defined as follows:

• Typeless, meaning they do not have associated messageTypes

• Not associated with any WSDL message

• Caught without a fault variable:

  <catch faultName="bpws:selectionFault"> 
  

8.4 Categories of BPEL Faults

A BPEL fault has a fault name called a Qname (name qualified with a namespace) and a possible messageType. There are two categories of BPEL faults:

• Business faults

• Run-time faults

<catch faultName="ns1:faultName" faultVariable="varName">

<?xml version="1.0" encoding="UTF-8" ?> 
<definitions name="RuntimeFault"
  targetNamespace="http://schemas.oracle.com/bpel/extension"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://schemas.xmlsoap.org/wsdl/">

  <message name="RuntimeFaultMessage">
   <part name="code" type="xsd:string" /> 
   <part name="summary" type="xsd:string" /> 
   <part name="detail" type="xsd:string" /> 
  </message>
</definitions>

8.5 Getting Fault Details with the getFaultAsString XPath Extension Function

The catchAll activity is provided to catch possible faults. However, BPEL does not provide a method for obtaining additional information about the captured fault. Use the getFaultAsString() XPath extension function to obtain additional information.

<catchAll>
   <sequence>
      <assign>
         <from expression="bpelx:getFaultAsString()"/>
         <to variable="faultVar" part="message"/>
      </assign>
      <reply faultName="ns1:myFault" variable="faultVar" .../>
   </sequence>
</catchAll>

8.6 Using the Scope Activity to Manage a Group of Activities

The scope activity provides a container and a context for other activities. A scope provides handlers for faults, events, and compensation, as well as data variables and correlation sets. Using a scope activity simplifies a BPEL flow by grouping functional structures together. This allows you to collapse them into what appears to be a single element in Oracle JDeveloper.

The following code example shows a scope activity. In this case, the process for getting a credit rating based on a customer's social security number has been placed inside a scope named getCreditRating. This identifies functional blocks of code and sets them apart visually. In Oracle JDeveloper, you can collapse the activities contained inside the scope into a single visual element, or expand them when necessary.

<scope name="getCreditRating">
     <variables>
          <variable name="crError"
            messageType="services:CreditRatingServiceFaultMessage"/>
     </variables>
          <assign name="assign-2">
               <copy>
                   <to variable="input" part="payload"
                    query="/autoloan:loanApplication/autoloan:creditRating"/>
               </copy>
          </assign>
     </sequence>
</scope>

To add a scope activity:

1. Click and drag a scope activity into the BPEL process diagram.

2. Open the scope by double-clicking it or by single-clicking the + sign.

3. Drag activities from the Component Palette to build the function within the scope.

8.7 Throwing Internal Faults

A BPEL application can generate and receive fault messages. The throw activity has three elements: its name, the name of the faultName, and the faultVariable. If you add a throw activity to your BPEL process, it automatically includes a copy rule that copies the fault name and type into the output payload. The fault thrown by a throw activity is internal to BPEL. You cannot use a throw activity on an asynchronous process to communicate with a client. Here is a code sample of a throw activity, which includes the fault elements, name, and partner link of the service to which the BPEL process sends the fault, and the copy rule that packages the message:

<throw name="delay" faultName="fault-1" faultVariable="fVar"/>
     <invoke name="invokeStockQuoteService" partnerLink="StockQuoteService"/>
     <assign>
        <copy>
           <from variable="response" part="result" query="/result"/>
           <to variable="output" part="payload" query="/tns:result"/>
        </copy>
     </assign>

8.8 Returning External Faults

A BPEL process can send a fault to another application to indicate a problem, as opposed to throwing an internal fault. In a synchronous operation, the reply activity can return the fault. In an asynchronous operation, the invoke activity performs this function.

<reply partnerlinke="partner-link-name"
       portType="port-type-name"
       operation="operation-name"
       variable="variable-name" (optional)
       faultName="fault-name">
</reply>

8.9 Using a Fault Handler within a Scope

If a fault is not handled, it creates a faulted state that migrates up through the application and can throw the entire process into a faulted state. To prevent this, contain the parts of the process that have the potential to receive faults within a scope. As described earlier, the scope activity includes fault handling capabilities. The catch activity works within a scope to catch faults and exceptions before they can throw the entire process into a faulted state.

You can use specific fault names in the catch activity to respond in a specific way to an individual fault. To catch any faults that are not already handled by name-specific catch activities, use the catchAll activity.

<empty standard-attributes>
    standard-elements
  </empty>

<faulthandlers>
   <catch faultName="x:foo">
         <empty/>
      </catch>
   <catch faultVariable="bar">
         <empty/>
      </catch>
   <catch faultName="x:foo" faultVariable="bar">
         <empty/>
      </catch>
   <catchAll>
         <empty/>
      </catchAll>
</faulthandlers>

8.10 Using Compensation After Undoing a Series of Operations

Compensation occurs when the BPEL process cannot complete a series of operations after some of them have already completed, and the BPEL process must backtrack and undo the previously completed transactions. For example, if a BPEL process is designed to book a rental car, a hotel, and a flight, it may book the car and the hotel and then be unable to book a flight for the right day. In this case, the BPEL flow performs compensation by going back and unbooking the car and the hotel.

You can invoke a compensation handler by using the compensate activity, which names the scope for which the compensation is to be performed (that is, the scope whose compensation handler is to be invoked). A compensation handler for a scope is available for invocation only when the scope completes normally. Invoking a compensation handler that has not been installed is equivalent to using the empty activity (it is a no-op). This ensures that fault handlers do not have to rely on state to determine which nested scopes have completed successfully. The semantics of a process in which an installed compensation handler is invoked more than once are undefined.If an invoke activity has a compensation handler defined inline, then the name of the activity is the name of the scope to be used in the compensate activity. The syntax is as follows:

<compensate scope="ncname"? standard-attributes>
    standard-elements
  </compensate>

The ability to explicitly invoke the compensate activity is the underpinning of the application-controlled error-handling framework of Business Process Execution Language for Web Services Specification. You can use this activity only in the following parts of a business process:

• In a fault handler of the scope that immediately encloses the scope for which compensation is to be performed.

• In the compensation handler of the scope that immediately encloses the scope for which compensation is to be performed.

For example:

<compensate scope="RecordPayment"/>

If a scope being compensated by name was nested in a loop, the BPEL process invokes the instances of the compensation handlers in the successive iterations in reverse order.

If the compensation handler for a scope is absent, the default compensation handler invokes the compensation handlers for the immediately enclosed scopes in the reverse order of the completion of those scopes.

The compensate form, in which the scope name is omitted in a compensate activity, explicitly invokes this default behavior. This is useful when an enclosing fault or compensation handler must perform additional work, such as updating variables or sending external notifications, in addition to performing default compensation for inner scopes. The compensate activity in a fault or compensation handler attached to the outer scope invokes the default order of compensation handlers for completed scopes directly nested within the outer scope. You can mix this activity with any other user-specified behavior except for the explicit invocation of the nested scope within the outer scope. Explicitly invoking a compensation for such a scope nested within the outer scope disables the availability of default-order compensation.

8.11 Using the Terminate Activity to Stop a Business Process Instance

The terminate activity immediately terminates the behavior of a business process instance within which the terminate activity is performed. All currently running activities must be terminated as soon as possible without any fault handling or compensation behavior. The terminate activity does not send any notifications of the status of a BPEL process. If you are going to use the terminate activity, first program notifications to the interested parties.

The syntax for the terminate activity is as follows:

<terminate standard-attributes>
    standard-elements
</terminate>

8.12 Fault Handling Example

The ResilientDemo sample demonstrates failover fault handling and retry fault handling. Failover allows multiple service implementations to be configured for a partner link. If a retryable run-time fault occurs, then the server tries other service implementations. In retry fault handling, the server retries based on a specified retry interval and retry count. Another kind of fault, a binding fault, can occur if the Web service has been upgraded and the interface has changed. In the ResilientDemo sample, when a binding fault occurs, the document is placed in a dead letter queue using a JMS service. The diagram of ResilientFlow.bpel is shown in .

Figure 8-2 Diagram Window of ResilientFlow.bpel

Description of the illustration resilient1.gif

The invokeRatingService activity shows the failover feature. The partner link of this invoke has two possible implementations, which are configured in the deployment descriptor file as follows:

<properties id="RatingService">
  <property name="wsdlLocation">
    http://localhost:8080/axis/services/RatingService1?wsdl
  </property>
  <property name="location">
    http://localhost:1234/axis/services/RatingService1
    http://localhost:8080/axis/services/RatingService2
  </property>
</properties>

The preceding code sample shows that two endpoint locations are configured for the RatingService partner link. The first endpoint is a bad URL and the second endpoint is a good URL. Because a remote exception like this is retryable, and there is a second endpoint, Oracle BPEL Server tries to call the second endpoint, at which point, the call succeeds.

The invokeFlakyService activity, expanded in , shows system retry.

Figure 8-3 Retry with FlakyService

Description of the illustration resilient2.gif

The partner link of this invoke is configured as follows:

<properties id="FlakyService">
  <property name="wsdlLocation">
     http://localhost:8080/axis/services/FlakyService?wsdl</property>  
  <property name="location">
     http://localhost:2222/axis/services/FlakyService</property>
  <property name="retryMaxCount">2</property>
  <property name="retryInterval">60</property>
</properties>

If the service is not listening on port 2222, then the invoke fails with a ConnectionRefused run-time fault. Because this is a retryable fault, and the retryMaxCount (set to 2) and retryInterval parameters (set to 60) are defined, Oracle BPEL Server retries twice, with 60 second intervals between each attempt. The second retry is successful.

8.13 Summary

BPEL supports fault handlers to cope with faults, errors, or exceptions returned by the called Web services. This chapter demonstrates the application of a fault handler, a fault handler's structure, and how to create a fault handler in a BPEL process.