Event Handlers

An event handler is a set of activities that run concurrently with either the primary activity of the same scope or, outside a scope, with the primary activity of the process. The handler also may run concurrently with other event handlers and with other instances of the same handler. Unlike the other handlers (compensation, fault, and termination), the event handler runs during normal processing.

Two kinds of event handlers are available: onEvent and onAlarm.

An onEvent handler processes an inbound message and is similar to a receive activity. You can use this kind of handler for an interaction that occurs only in some process instances, as when a customer cancels a purchase before a product is shipped.

An onAlarm handler waits for a passage of time or for a specific date and time. After firing an initial alarm, the handler can fire an alarm repeatedly at a specified interval. You can use an onAlarm handler to send a renewal notice.

An event handler is enabled when the BPEL process receives its initial message or when the scope that encloses the event handler begins. An event handler is disabled when the process or scope ends. If an event handler is running, though, the BPEL engine allows the activities to complete.

The onEvent handler accepts messages for as long as the handler is enabled, whereas the onAlarm handler does not fire again unless you requested a repetition.

onEvent Handler

The BPEL process implicitly declares a variable that receives data and is local to the scope of the handler. You can receive data only into that implicitly declared variable.

The implicit declaration occurs whether you've specified the variable attribute, along with a message type or XSD element, or the fromParts element. (We've ignored the possibility of several variable declarations, one for each part in the inbound message.) All local variables in the scope of the handler are local to each running instance of the handler.

Among the attributes of the onEvent handler:

• partnerLink identifies the partner link used to connect to the service.

• portType identifies the port type but is optional because the port type is implied by the partner link and by the role identifier myRole in that partner link.

• operation identifies the service operation.

• variable identifies a variable that receives the business data from the service. Specify the variable attribute only if you don't specify the fromParts element.

• messageExchange references a message exchange in a scope that encloses the onEvent handler.

Among the elements in the onEvent handler:

• correlations references one or more correlation sets.

• fromParts identifies a set of message parts and related variables to receive business data. Specify the fromParts element only if you don't specify the variable attribute.

onAlarm Handler

The onAlarm handler requires the presence of at least one of the following elements:

• for identifies the duration that passes before the alarm is fired. The start time for that duration is when the BPEL process receives its initial message or when the scope that encloses the event handler begins. You can specify this element only if you don't specify the until element.

• until identifies the calendar date and clock time when the alarm is triggered. You can specify this element only if you don't specify the for element.

• repeatEvery causes the alarm to be triggered repeatedly and specifies the interval between triggers. The interval begins when the initial trigger fires or, if neither of the other elements is specified, when the BPEL process receives its initial message or when the scope that encloses the event handler begins.

Listing 8.13 shows several onAlarm handler examples.

Listing 8.13: onAlarm handlers

 <process>    <eventHandlers>       <!- the event fires after 5 minutes ->       <onAlarm>          <for>'PT5M'</for>          <invoke .../>       </onAlarm>       <!- the event fires at 9am on Dec 24 2010 ->       <onAlarm>          <until>'2010-12-24T09:00+01:00'</until>          <invoke .../>       </onAlarm>       <!- the event fires every 3 hours ->       <onAlarm>          <repeatEvery>'PT3H'</repeatEvery>          <invoke .../>       </onAlarm>       <!- the event fires after 5 minutes            and every day thereafter ->       <onAlarm>          <for>'PT5M'</for>          <repeatEvery>'P1D'</repeatEvery>          <invoke .../>       </onAlarm>    </eventHandlers> </process> 

You can assign some or all of the element values from data that was received in an inbound message. Also, if you wish to fire the alarm repeatedly but only a specified number of times, you can create a sequential forEach activity and embed an onAlarm handler that doesn't have a repeatEvery element.