Using event handlers

Configuring an event handler

You can define and configure an event handler either on individual scopes within the process, or for the whole process in its entirety.

There are two parts to an event handler. The first part defines the conditions under which an event handler is to be invoked; that is, it defines the type of the event handler. You have the two following choices:

Element	Icon	Description
OnEvent element		Use this element to create a control path and specify the operation that will cause this path to be followed.
Timeout element		Use this element to create a control path that is followed when a specified time has either been reached or has elapsed. This element is used on a single path, and is configured to specify either a specific date, or period of time. When the process is running, this path is chosen when no input is received within this time period, or by the specified date.

Lifecycle of an event handler

Each event handler is enabled when the process or scope it is associated with starts. Each event handler is disabled when the process or scope it is associated with ends. Multiple instances of each event handler can be started as long as the event handler is enabled. If instances of event handlers are still running when a scope ends, then they are allowed to complete.

It is important to distinguish between enablement and dispatching. An event handler is said to be enabled once the associated scope starts. An onEvent event handler instance is said to be dispatched when the event handler is enabled, and the associated operation is invoked on the process. Similarly, an onAlarm event handler instance is dispatched when the event handler is enabled, and the specified timeout is reached.

Fault handling

Event handlers are considered a part of the normal processing of a scope. Faults within event handlers are treated like faults in the associated scope. If a fault occurs within a scope (or in an event handler associated with the scope) the fault handler disables all event handlers associated with the scope and then implicitly terminates all activities directly enclosed within the scope that are currently active. This includes the activities within currently active event handlers.

Concurrency

Multiple onEvent and timeout events can occur concurrently and they are treated as concurrent activities. An event handler is permitted to have several simultaneously active instances. A private copy of all process data and control behavior defined within an event handler is provided to each instance of an event handler.

Restrictions

Conflicting receive

Multiple event handlers with the identical port type, operation, correlation set, and partner link cannot be activated simultaneously, otherwise a bpws:conflictingReceive standard fault is thrown because the process engine does not know which activity to deliver an incoming message to.

Business Process Choreographer is even more restrictive in its concurrency requirements. Because it cannot distinguish incoming messages based on correlation sets or partner links, Business Process Choreographer does not allow more than one receive or pick activity to be active with the same port type and operation in a given process instance.

This restriction means, for example, that a bpws:conflictingReceive standard fault is thrown in the following situations:

• A receive or pick activity with a certain port type and operation is activated while another pick or receive activity with the same port type and operation is already waiting
• An event handler with a certain port type and operation is enabled and then a receive or pick activity with the same port type and operation is activated
• A receive or pick activity with a certain port type and operation is waiting and then an event handler with the same port type and operation is enabled.

Conflicting request

Similarly, if multiple request-response operations share a port type, operation, correlation set, or partner links, then a bpws:conflictingRequest standard fault exception is thrown because the client cannot distinguish the source of the reply.

Business Process Choreographer only allows one concurrently active request-response operation per process instance, port type, and operation. The effect of this is that if an event handler implements a request-response operation, then only one instance of such an event handler may be active at any point in time.

Isolated scopes

If an event handler contains an isolated scope (one that has concurrent access to shared variables), and multiple instances of this event handler are started, then concurrent processing of these instances is severely constrained. Since this may contradict the whole idea of event handlers, you should use isolated scopes carefully within event handlers. You need isolated scopes only if your scope reads a global variable in one transaction and updates the same global variable in another transaction. In most situations it is possible to avoid such a variable access pattern.