11 Events and Timeouts

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

This chapter contains the following topics:

Use Case for Events and Timeouts
Overview of Event and Timeout Concepts
Using the Pick Activity to Select Between Continuing a Process or Waiting
Using the Wait Activity to Set an Expiration Time
Setting Timeouts for Synchronous Processes
Defining a Timeout in JDeveloper BPEL Designer
Summary

11.1 Use Case for Events and Timeouts

In this use case, you program a BPEL process to wait one minute for a response from the Star Loan Web service. If Star Loan does not respond in one minute, then the BPEL process automatically selects the United Loan offer. 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 is working properly.

11.2 Overview of Event and Timeout Concepts

Because asynchronous Web services can take a long time to return a response, a BPEL process 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.

If you plan to set timeouts for synchronous processes that connect to a remote database, you need to set the syncMaxWaitTime timeout property in the domain.xml file.

11.3 Using the 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 11-1 provides an overview. The following activities take place:

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 is the same as 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, and 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.
  
  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 executes. The other branch then is not executed.

Figure 11-1 Overview of the Pick Activity

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

The following code segment defines the pick activity for this operation:

  <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>

11.4 Using the 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.

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

11.5 Setting Timeouts for Synchronous Processes

For synchronous processes that connect to a remote database, you must increase the syncMaxWaitTime timeout property in the Oracle_Home\integration\orabpel\domains\default\config\domain.xml file:

<property id="syncMaxWaitTime"> 
        <name>Delivery result receiver maximum wait time</name> 
        <value>60000000</value> 
        <comment> 
        <![CDATA[The maximum time the process result receiver will wait for a 
result before returning.  Results from asynchronous BPEL processes are 
retrieved synchronously via a receiver that will wait for a result from the 
container. 
        <p/> 
        The default value is 60 seconds.]]> 
        </comment> 
    </property>

Note:

For Eclipse BPEL Designer, domain.xml is located in the c:\orabpel\domains\default\config directory.

11.6 Defining a Timeout in JDeveloper BPEL Designer

To define a timeout in JDeveloper BPEL Designer, follow these steps:

Drag the pick activity from the Component Palette, and place it just before the receive activity for the Star Loan service.

The pick activity includes the onMessage and onAlarm branches.

Description of the illustration pick2.gif
Double-click the OnAlarm branch of the onAlarm activity and set its time limit to 1 minute instead of 1 hour.

Description of the illustration pick3.gif
Press OK when complete.
Double-click the onMessage activity, and edit its attributes to receive the response from the loan service.

Description of the illustration pick4.gif
For each of the onMessage and onAlarm branches, drag an empty assign activity onto its Drop activity here area. In other instances, this space can contain additional logic and processing.

Description of the illustration pick5.gif

See Also:
"Pick Activity"

11.7 Summary

Instead of performing multiple operations at the same time as with the flow attribute, you can use the pick activity to define a number of operations such that only the first one to complete is executed. The example in this chapter is of a pick activity where one branch is an asynchronous callback from the Star Loan service, and the other branch is a timeout set at one minute.