14 Using Events and Timeouts in BPEL Processes

This chapter describes how to use events and timeouts. Because web services can take a long time to return a response, a BPEL process service component must be able to time out and continue with the rest of the flow after a period of time.

This chapter includes the following sections:

Section 14.1, "Introduction to Event and Timeout Concepts"
Section 14.2, "Creating a Pick Activity to Select Between Continuing a Process or Waiting"
Section 14.3, "Setting Timeouts for Request-Response Operations in Receive Activities"
Section 14.4, "Creating a Wait Activity to Set an Expiration Time"
Section 14.5, "Setting Timeouts for Synchronous Processes"

14.1 Introduction to Event and Timeout Concepts

This chapter provides an example of how to program a BPEL process service component to wait one minute for a response from a web service named Star Loan that provides loan offers. If Star Loan does not respond in one minute, then the BPEL process service component automatically selects an offer from another web service named United Loan. In the real world, the time limit is more like 48 hours. However, for this example, you do not want to wait that long to see if your BPEL process service component is working properly.

Because asynchronous web services can take a long time to return a response, a BPEL process service component must be able to time out, or give up waiting, and continue with the rest of the flow after a certain amount of time. You can use the pick activity to configure a BPEL flow to either wait a specified amount of time or to continue performing its duties. To set an expiration period for the time, you can use the wait activity.

14.2 Creating a Pick Activity to Select Between Continuing a Process or Waiting

The pick activity provides two branches, each one with a condition. The branch that has its condition satisfied first is executed. In the following example, one branch's condition is to receive a loan offer, and the other branch's condition is to wait a specified amount of time.

Figure 14-1 provides an overview. The following activities take place (in order of priority):

An invoke activity initiates a service, in this case, a request for a loan offer from Star Loan.
The pick activity begins next. It has the following conditions:
- onMessage
  
  This condition has code for receiving a reply in the form of a loan offer from the Star Loan web service. The onMessage code matches the code for receiving a response from the Star Loan web service before a timeout was added.
- onAlarm
  
  This condition has code for a timeout of one minute. This time is defined as PT1M, which means to wait one minute before timing out. In this timeout setting:
  - S stands for seconds
  - M for one minute
  - H for hour
  - D for day
  - Y for year
  In the unlikely event that you want a time limit of 1 year, 3 days, and 15 seconds, you enter it as PT1Y3D15S. The remainder of the code sets the loan variables selected and approved to false, sets the annual percentage rate (APR) at 0.0, and copies this information into the loanOffer variable.
  
  The time duration format is specified by the BPEL standard. For more detailed information on the time duration format, see the duration section of the most current XML Schema Part 2: Datatypes document at:
```
http://www.w3.org/TR/xmlschema-2/#duration
```
The pick activity condition that completes first is the one that the BPEL process service component executes. The other branch then is not executed.

Figure 14-1 Overview of the Pick Activity

Description of "Figure 14-1 Overview of the Pick Activity"

14.2.1 How To Create a Pick Activity

To create a pick activity:

In the SOA Composite Editor, double-click the BPEL process service component.
From the Component Palette, drag a Pick activity into the designer.
Expand the Pick activity.

The Pick activity includes the onMessage (envelope icon) and onAlarm (alarm clock icon) branches. Figure 14-2 provides an example.

Figure 14-2 Pick Activity

Description of "Figure 14-2 Pick Activity"
Double-click the OnAlarm branch of the pick activity and set its time limit to 1 minute instead of 1 hour. Figure 14-3 provides an example.

Figure 14-3 OnAlarm Branch

Description of "Figure 14-3 OnAlarm Branch"
Click OK.
Double-click the onMessage branch. Figure 14-4 provides an example.

Figure 14-4 onMessage Branch

Description of "Figure 14-4 onMessage Branch"
Edit its attributes to receive the response from the loan service.

14.2.2 What Happens When You Create a Pick Activity

The code segment in Example 14-1 defines the pick activity for this operation after design completion:

Example 14-1 Pick Activity

  <pick>
        <!--  receive the result of the remote process -->
        <onMessage partnerLink="LoanService"
            portType="services:LoanServiceCallback"
            operation="onResult" variable="loanOffer">
            
        <assign>
        <copy>
            <from variable="loanOffer" part="payload"/>
            <to variable="output" part="payload"/>
        </copy>
        </assign> 
        
       </onMessage>
       <!--  wait for one minute, then timesout -->
       <onAlarm for="PT1M">
            <assign>
                <copy>
                    <from>
                        <loanOffer xmlns="http://www.autoloan.com/ns/autoloan">
                            <providerName>Expired</providerName> 
                            <selected type="boolean">false</selected> 
                            <approved type="boolean">false</approved> 
                            <APR type="double">0.0</APR> 
                        </loanOffer>
                    </from> 
                    <to variable="loanOffer" part="payload"/>
                </copy>
            </assign>
       </onAlarm>
</pick>

14.3 Setting Timeouts for Request-Response Operations in Receive Activities

You can provide a timeout setting for request-response operations in receive activities. This provides an alternative to using the onMessage and onAlarm branches of a pick activity to specify a timeout duration for partner callbacks.

The following sections provide an overview of this functionality:

Timeout settings relative from activity invocation
Timeout settings as an absolute date time
Timeout settings computed dynamically with an XPath expression
bpelx:timeout fault thrown during an activity timeout
Event added to the BPEL instance audit trail during an activity timeout
Recoverable timeout activities during a server restart

14.3.1 Timeout Settings Relative from When the Activity is Invoked

You can specify a timeout setting relative from when the activity is invoked. This setting is specified as a relative duration using the syntax shown in Example 14-2.

Example 14-2 Timeout Settings Relative from When the Activity is Invoked

<receive | bpelx:for="duration-expr">
    standard-elements
</receive>

This type uses the bpelx:for attribute to specify a static value or an XPath expression that must evaluate to an XML schema type duration. Only one of the bpelx:for or bpelx:until attributes is permitted for an activity.

If the XPath expression evaluates to a negative duration, the timeout is ignored and an event is logged to the instance audit trail indicating that the duration value is invalid.

Once a valid duration value is retrieved, the expiration date for the activity is set to the current node time (or cluster time after this is available), plus the duration value. For example, the duration value bpelx:for="'PT5M'" specifies that the activity expects an inbound message to arrive no later than five minutes after the activity has started execution.

Note:

The timeout setting attribute does not apply to the onMessage branch of a pick activity because the same functionality currently exists with the onMessage and onAlarm branches of that activity.

Timeout durations can only be specified on the following:

Midprocess receive activities
Receive activities that do not specify createInstance="true"

A receive activity can only time out after it has been instantiated, which is not the case with entry receive activities.

14.3.2 Timeout Settings as an Absolute Date Time

You can specify a timeout setting as an absolute deadline for request-response receive activities. This type uses the syntax shown in Example 14-3.

Example 14-3 Timeout Settings as an Absolute Date Time

<receive bpelx:until="deadline-expr">
    standard-elements
</receive>

The expected expiration time for the bpelx:until attribute must be at least two seconds ahead of the current time. Otherwise, the timer scheduling is ignored and skipped, just as if the timer was never specified.

The bpelx:until attribute specifies a static value or an XPath expression that must evaluate to an XML schema type datetime or date. Only one of the bpelx:for or bpelx:until attributes is permitted for an activity.

XPath version 1.0 is not XML schema-aware. Therefore, none of the built-in functions of XPath version 1.0 can create or manipulate dateTime or date values. However, it is possible to perform one of the following:

Write a constant (literal) that conforms to XML schema definitions and use that as a deadline value
Extract a field from a variable (part) of one of these types and use that as a deadline value

XPath version 1.0 treats that literal as a string literal, but the result can be interpreted as a lexical representation of a dateTime or date value.

Once a valid datetime or date value has been retrieved, the expiration date for the activity is set to the specified date. For example, the datetime value bpelx:until="'2009-12-24T18:00+01:00'" specifies that the activity expects an inbound message to arrive no later than Dec 24, 2009 6:00 pm UTC+1 after the activity has started execution.

Note:

The timeout setting attribute does not apply to the onMessage branch of a pick activity because the same functionality currently exists with the onMessage and onAlarm branches of the pick activity.

Timeout dates can only be specified on the following activities:

Midprocess receives
Receive activities that do not specify createInstance="true"

A receive activity can only time out after it has been instantiated, which is not the case with entry receive activities.

14.3.3 Timeout Settings Computed Dynamically with an XPath Expression

The timeout setting for request-response receive and onMessage branches of pick activities can be set using an XPath expression instead of entering a static duration or datetime value. In this case, the value of the expression must return either:

A string that can be interpreted as a static XML duration or datetime value
An XML schema duration or datetime type

Example 14-4 shows the syntax for using XPath expressions.

Example 14-4 Timeout Settings Computed Dynamically with an XPath Expression

<bpelx:for="bpws:getVariableData('input', 'payload',
 '/tns:waitValue/tns:for')"/>

<bpelx:until="bpws:getVariableData('input', 'payload',
 '/tns:waitValue/tns:until')"/>

If the returned expression value cannot be interpreted as an XML schema duration or datetime type, an event is logged in the instance audit trail indicating that an invalid duration and datetime value was specified, and no activity expiration time can be set.

14.3.4 bpelx:timeout Fault Thrown During an Activity Timeout

If a valid XML schema duration or datetime value is returned from the bpelx:for or bpelx:until attribute, a bpelx:timeout fault is thrown from the timed-out activity. This fault can be caught by any catch or catchAll block and handled like a regular BPEL fault. The message of the fault is the name of the activity. In addition, an event is logged to the instance audit trail indicating that the activity has timed out because the expected callback message failed to be received before the timeout duration.

If the activity receives a callback from the partner before the timeout period, no fault is thrown. If a callback is received while the activity is being timed out, the callback message is not delivered to the activity and it is marked as canceled in the delivery message table. If a timeout action is attempted at the same time that a callback message is handled, the timeout action is ignored. As of 11g Release 1, instances are locked optimistically (as opposed to pessimistic locking in Release 10g). Therefore, the second action in line is still performed. However, the instance version check fails upon dehydration of the instance.

The bpelx:timeout fault can be thrown from a BPEL component if the component WSDL declares the fault on the operation. If the fault is not declared on the operation, the fault is converted into a FabricInvocationException, which is a runtime fault. This fault can be caught by any caller components (including BPEL components), but the fault type is no longer bpelx:timeout (however, the fault message string still indicates that the fault was originally a timeout fault).

14.3.5 Event Added to the BPEL Instance Audit Trail During an Activity Timeout

Once a bpelx:timeout fault is thrown from a timed-out activity, an event is logged to the instance audit trail indicating that the activity has timed out, as opposed to having received the expected callback message from its partner.

14.3.6 Recoverable Timeout Activities During a Server Restart (Refresh Expiration Alarm Table)

Activities that specify a valid timeout duration or datetime are likely implemented in a similar manner to wait and onAlarm activities with an expiration date for the underlying work item object. If the node that scheduled these activities with the scheduler goes down (either through graceful shutdown or abrupt termination), all these activities must be rescheduled with the scheduler upon server restart.

It is not possible to have a single node (the master node) in the cluster be responsible for rescheduling these activities upon node shutdown.

14.3.7 How to Set Timeouts for Request-Response Operations in Receive Activities

To set timeouts for request-response operations in receive activities:

In the SOA Composite Editor, double-click the BPEL process service component.
From the Component Palette, drag a receive activity into the designer.
Expand the activity.
Click the Timeout tab.

This tab enables you to set a timeout for request-response operations, as shown in Figure 14-5.

Figure 14-5 Timeout Tab

Description of "Figure 14-5 Timeout Tab"
Specify appropriate values, and click Apply. For example:
- To specify a timeout setting relative from when the activity is invoked, click the For button and enter a value or click the Expression button and specify an XPath expression.
- To specify a timeout setting as an absolute deadline for a request-response operation, click the Until button and enter a value or click the Expression button and specify an XPath expression.
Click Apply, then OK.

14.3.8 What Happens When You Set Timeouts for Request-Response Operations in Receive Activities

The code segment in the .bpel file defines the specific operation after design completion.

For example, if you specified that the activity expects an inbound message to arrive no later than five minutes after the activity has started execution, the syntax displays as shown in Example 14-5.

Example 14-5 Static Duration

bpelx:for="'PT5M'"/>

For example, if you specified that the activity expects an inbound message to arrive no later than January 24, 2010 11:00 am UTC+1 after the activity has started execution, the syntax displays as shown in Example 14-6.

Example 14-6 datetime Value

bpelx:until="'2010-01-24T11:00:00-08:00'"/>

For example, if you specified an XPath expression to obtain a value for a timeout relative from when the activity is invoked, syntax similar to that shown in Example 14-7 can display.

Example 14-7 XPath Expression

bpelx:for="bpws:getVariableData('inputVariable','payload','/tns:waitValue/tns:for')"/>

14.4 Creating a Wait Activity to Set an Expiration Time

The wait activity allows a process to wait for a given time period or until a time limit has been reached. Exactly one of the expiration criteria must be specified. A typical use of this activity is to invoke an operation at a certain time. You typically enter an expression that is dependent on the state of a process.

When specifying a time period for waiting, note the following:

Wait times cannot be guaranteed if they are scheduled with other events that require processing. Due to this additional processing, the actual wait time can be greater than the wait time specified in the BPEL process.
Wait times of less than two seconds are ignored by the server. Wait times above two seconds, but less than one minute, may not get executed in the exact, specified time. However, wait times in minutes do execute in the specified time.
The default value of 2 seconds for wait times is specified with the MinBPELWait property in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control Console. You can set this property to any value and the wait delay is bypassed for any waits less than MinBPELWait.

Note:

Quartz version 1.6 is supported for scheduling expiration events on wait activities.

14.4.1 How To Specify the Minimum Wait Time

You can specify the minimum time duration for a BPEL process to perform a wait that involves a dehydration. If the wait duration is less than or equal to the value, BPEL continues executing activities in the same thread and transaction.

From the SOA Infrastructure menu, select SOA Administration > BPEL Properties.
At the bottom of the BPEL Service Engine Properties page, click More BPEL Configuration Properties.
Click MinBPELWait.
In the Value field, specify a value in seconds.
Click Apply.
Click Return.

14.4.2 How to Create a Wait Activity

To create a wait activity:

From the Component Palette, drag a Wait activity into the designer.
Double-click the Wait activity to display the Wait dialog.
In the For section, enter the amount of time for which to wait.
In the Until section, select the deadline for which to wait, as shown in Figure 14-6.

Figure 14-6 Wait Dialog

Description of "Figure 14-6 Wait Dialog"

14.4.3 What Happens When You Create a Wait Activity

Exactly one of the expiration criteria must be specified, as shown in Example 14-8.

Example 14-8 Wait Activity

<wait (for="duration-expr" | until="deadline-expr") standard-attributes>
    standard-elements
  </wait>

14.5 Setting Timeouts for Synchronous Processes

For synchronous processes that connect to a remote database, you must increase the SyncMaxWaitTime timeout property in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control Console.

For information on setting this property, see Section 7.3, "Specifying Timeout Values."