test

Developer Guide to the BPEL Designer

Using Handlers

The following sections describe, in order of their appearance:

Using a Fault Handler

Using an Event Handler

Using a Compensation Handler

Using a Termination Handler

Using a Fault Handler

When to Use

The BPEL language provides the capability to catch and manage exceptions using fault handlers. For example, exceptions occur when web services return different data than was expected. If faults are not handled, the entire BPEL process can be thrown into a faulted state. Therefore, to prevent the entire process from fault, you can add fault handlers to catch and manage exceptions within particular Scopes.

Each fault handler contains an activity that runs in case of an error. For example, a partner service is notified if an error has occurred. Fault handlers can be added to the entire process or to individual Scope elements.

You can attach one Fault Handler container to either the Process or the Scope elements. Inside the Fault Handlers container, you can create several Catch activities configured to catch specific kinds of faults, or one Catch All handler element to catch all the exceptions not caught by specific handlers.

Usage

  1. Right-click the Scope or Process element and choose Add > Fault Handlers.

    An empty container element appears.

  2. Right-click the Fault Handler container and choose Add > Catch or Add > Catch All.

    You may add as many specific Catch elements as you wish to the Fault Handlers group. You can add only one Catch All element per Fault Handlers container.

  3. Add an activity to the Catch or Catch All element that will be executed in case of a fault.

Catch Element

Use this element to intercept and deal with a specific kind of fault.

This element is used within an appropriate Fault Handlers container element.

Catch Element Properties

The properties of the Catch element are defined in the Properties window. You can also right-click the element on the diagram and choose Properties. The available properties are:

Catch Properties Window

Catch All Element

Use the Catch All element to intercept and deal with all faults that are not caught by an associated catch element.

The Catch All element is used within a fault handler window along with one or more Catch elements. It is defined within a Fault Handlers container element along with one or more Catch elements.

There are no properties for the Catch All element. Its behavior is pre-defined and requires no property configuration.

Using an Event Handler

When to Use

The entire BPEL process as well as each individual Scope can be associated with a set of Event Handlers that are invoked concurrently if the corresponding event occurs. The actions taken within an Event Handler can be any type of activity, such as Sequence or Flow. The only immediate child of an Event Handler is Scope, so when you drag an element from the Palette into an Event Handler, it is automatically wrapped in Scope.

There are two types of events:

Usage

  1. Right-click the Process element or any Scope and invoke the Add Event Handlers action. This does not add any particular Event Handler, it adds a container element to which you can then add specific Event Handlers.

  2. Once you have added an Event Handlers container, you can right-click on the Event Handlers element to add an On Event or On Alarm branch. You may add as many specific On Event or On Alarm elements as you wish to the Event Handlers group.

On Event Element

The On Event element indicates that the specified event waits for a message to arrive. The interpretation of this tag and its attributes is very similar to a Receive activity.

Usage

  1. Right-click the Event Handlers container and choose Add > On Event.

  2. Double-clicking the On Event element opens a Property Editor where you can specify/change the following:

    • The partner link

    • The operation associated with the On Event element

    • The event variable

    OnEvent Property Editor

  3. Right-clicking the On Event element and choosing Properties opens a Properties window where you can review and modify the properties of the element. In addition to the properties present in the Property Editor dialog box, the Properties window contains the Port Type field, which are filled in when you specify the partner link and operation, and the Type field, which is filled with the type of the specified even variable.

OnEvent Properties Window

The Correlations tab in the On Event Property Editor dialog box enables you to examine or specify a correlation set.

The tab shows:

For more information see Understanding Correlation. Using the Correlation Wizard.

On Alarm Element

The On Alarm element specifies the deadline for or the duration of the nested Scope.

On Alarm Element Properties

The properties of the On Alarm element are defined in the Properties window, invoked by right-clicking the element on the diagram and choosing Properties. The available properties are:

Using a Compensation Handler

When to Use

A business process often contains several nested transactions. The overall business transaction can fail or be cancelled after many enclosed transactions have already been processed. Then it is necessary to reverse the effect obtained during process execution. For example, a travel planning process can include several nested transactions to book a ticket, to reserve a hotel and a car. If the trip is cancelled, the reservation transactions must be compensated for by cancellation transactions in the appropriate order. For such cases, WS-BPEL provides you with the capability to define compensation actions. A Compensation Handler is a container for the activities that perform compensation actions. You can add one Compensation Handler to either the Scope or the Invoke elements. The compensation handler can be invoked by Using the CompensateScope ElementUsing the Compensate Element activity.

ProcedureTo add a Compensation Handler to Scope or Invoke elements:

  1. Right-click the Scope or Invoke element and choose Add > Compensation Handler. An empty container element appears.

  2. From the Palette, drag one or several activities that will be executed and place them inside the Compensation Handler container. Configure the properties of each activity.

    Note –

    You do not have to configure any properties for the compensation handler.

Using a Termination Handler

When to Use

The termination handler is used to control the termination of a running scope. The termination of a running scope happens if a scope or process enclosing it has faulted.

When a fault is thrown inside a scope or process, a fault handler associated with the scope or process should be run, but before that all the running activities inside the faulted scope or process should be terminated. If a faulted scope or process has any enclosed scopes which are still running, they also should be terminated. Terminating a scope means terminating activities inside it and executing the termination handler associated with the scope.

Note that a scope can be terminated only if, it is either running normally, is running its compensation handler or termination handler. A completed scope as well as a scope that is faulted or is running its fault handlers cannot be terminated.

The termination handler is a container for the activities that will be performed in case a scope is terminated. You can add one termination handler for a scope.

If a fault occurs inside the termination handler of a scope, the fault is not propagated to the enclosing scope.

ProcedureTo add a Termination Handler to Scope or Process elements:

  1. In the Design view right-click the Scope element and choose Add > Termination Handler. An empty container element appears.

  2. From the Palette, drag one or several activities that will be executed and place them inside the Termination Handler container. Configure the properties of each activity.

    Note –

    You do not have to configure any properties for the termination handler.