Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.5.0)

Part Number E10224-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

8 Invoking an Asynchronous Web Service from a BPEL Process

This chapter describes how to call an asynchronous web service. Asynchronous messaging styles are useful for environments in which a service, such as a loan processor, can take a long time to process a client request. Asynchronous services also provide a more reliable fault-tolerant and scalable architecture than synchronous services.

This chapter includes the following sections:

8.1 Introduction to Invoking an Asynchronous Web Service

This section introduces asynchronous web service invocation with a company called United Loan. United Loan publishes an asynchronous web service that processes a client's loan application request and then returns a loan offer. This use case discusses how to integrate a BPEL process service component with this asynchronous loan application approver web service.

This use case illustrates the key design concepts for requesting information from an asynchronous service, and then receiving the response. The asynchronous United Loan service in this example is another BPEL process service component. However, the same BPEL call can interact with any properly designed web service. The target web service WSDL file contains the information necessary to request and receive the necessary information.

For the asynchronous web service, the following actions take place (in order of priority):

  1. An assign activity prepares the loan application.

  2. An invoke activity initiates the loan request. The contents of this request are put into a request variable. This request variable is sent to the asynchronous loan processor web service.

    When the loan request is initiated, a correlation ID unique to the client and partner link initiating the request is also sent to the loan processor web service. The correlation ID ensures that the correct loan offer response is returned to the corresponding loan application requester.

  3. The loan processor web service then sends the correct response to the receive activity, which has been tracked by the correlation ID.

  4. An assign activity reads the loan application offer.

The remaining sections in this chapter provide specific details about the asynchronous functionality.

8.2 Invoking an Asynchronous Web Service

This section provides an overview of the tasks for adding asynchronous functionality to a BPEL process service component.

8.2.1 How to Invoke an Asynchronous Web Service

You perform the following steps to asynchronously invoke a web service:

  • Add a partner link

  • Add an invoke activity

  • Add a receive activity

  • Create assign activities

8.2.1.1 Adding a Partner Link for an Asynchronous Service

These instructions describe how to create a partner link in a BPEL process (for this example, named LoanService) for the loan application approver web service.

To add a partner link for an asynchronous service:

  1. In the SOA Composite Editor, drag a BPEL process from the Service Components section of the Component Palette into the designer.

    The Create BPEL Process dialog appears.

  2. Follow the instructions in the dialog to create a BPEL process service component.

  3. Click OK when complete.

  4. In the SOA composite application in the SOA Composite Editor, double-click the BPEL process service component (for this example, the component is named LoanBroker).

    The Oracle BPEL Designer appears.

  5. In the Component Palette, expand BPEL Constructs.

  6. Drag a Partner Link icon into the right Partner Links swimlane.

    The Create Partner Link dialog appears.

  7. Enter the following details to create a partner link and select the loan application approver web service:

    • Name

      Enter a name for the partner link (for this example, LoanService is entered).

    • Process

      Displays the BPEL process service component name (for this example, LoanBroker appears).

    • WSDL URL

      Enter the name of the Web Services Description Language (WSDL) file to use. Click the SOA Resource Lookup icon above this field to locate the correct WSDL.

    • Partner Link Type

      Refers to the external service with which the BPEL process service component is to interface. Select from the list (for this example, LoanService is selected).

    • Partner Role

      Refers to the role of the external source, for example, provider. Select from the list (for this example, LoanServiceProvider is selected).

    • My Role

      Refers to the role of the BPEL process service component in this interaction. Select from the list (for this example, LoanServiceRequester is selected).

  8. Click OK.

    A new partner link for the loan application approver web service (United Loan) appears in the swimlane of the designer.

8.2.1.2 Adding an Invoke Activity

Follow these instructions to create an invoke activity and a global input variable named request. This activity initiates the asynchronous BPEL process service component activity with the loan application approver web service (United Loan). The loan application approver web service uses the request input variable to receive the loan request from the client.

To add an invoke activity:

  1. In the Component Palette, expand BPEL Constructs.

  2. Drag an Invoke activity to beneath the Receive activity.

  3. Go to the Structure window. Note that while this example describes variable creation from the Structure window, you can also create variables by clicking the Add icons to the right of the Input and Output fields of the Invoke dialog.

  4. Right-click Variables and select Expand All Child Nodes.

  5. In the second Variables folder in the tree, right-click and select Create Variable.

    The Create Variable dialog appears.

  6. Enter the variable name and select Message Type from the options provided:

    • Type

      This option lets you select an XML schema simple type (for example, string, boolean, and so on).

    • Message Type

      This option enables you to select a WSDL message file definition of a partner link or of the project WSDL file of the current BPEL process service component (for example, a response message or a request message). You can specify variables associated with message types as input or output variables for invoke, receive, or reply activities.

      To display the message type, select the Message Type option, and then select its Browse icon to display the Type Chooser dialog. From here, expand the Message Types tree to make your selection. For this example, Message Types > Partner Links > Loan Service > LoanService.wsdl > Message Types > LoanServiceRequestMessage is selected.

    • Element

      This option lets you select an XML schema element of the project schema file or project WSDL file of the current BPEL process service component, or of a partner link.

    Figure 8-1 shows the Create Variable dialog.

    Figure 8-1 Create Variable Dialog

    Description of Figure 8-1 follows
    Description of "Figure 8-1 Create Variable Dialog"

  7. Click OK.

  8. Double-click the invoke activity to display the Invoke dialog.

  9. In the Invoke dialog, select the partner link from the Partner Link list (for this example, LoanService is selected) and initiate from the Operation list.

  10. To the right of the Input field, click the second icon and select the input variable you created in Step 6.

    The Variable Chooser dialog appears, where you can select the variable.

    There is no output variable specified because the output variable is returned in the receive operation. The invoke activity is created.

    For more information about the invoke activity, see Section 8.2.2.5, "Invoke and Receive Activities."

  11. Click OK.

8.2.1.3 Adding a Receive Activity

Follow these steps to create a receive activity and a global output variable named response. This activity waits for the loan application approver web service's callback operation. The loan application approver web service uses this output variable to send the loan offer result to the client.

To add a receive activity:

  1. From the Component Palette, drag a Receive activity to the location right after the Invoke activity you created in Section 8.2.1.2, "Adding an Invoke Activity."

  2. Create a variable to hold the receive information by invoking the Create Variable dialog, as you did in Step 3 through Step 7 of Section 8.2.1.2, "Adding an Invoke Activity."

    Figure 8-2 shows the Create Variable dialog in BPEL 1.1.

    Figure 8-2 Create Variable Dialog

    Description of Figure 8-2 follows
    Description of "Figure 8-2 Create Variable Dialog"

    Not :

    In BPEL projects that support version 2.0 of the BPEL specification, the Create Variable dialog includes an Initialize tab that enables you to initialize the variable type inline (for example, as a variable, expression, literal, partner link, or property). For more information, see Section 6.5.2, "Initializing Variables with an Inline from-spec in BPEL 2.0."
  3. Double-click the receive activity and change its name to receive_invoke.

  4. From the Partner Link list, select the partner link (for this example, LoanService is selected).

  5. From the Operation list, select onResult. Do not select the Create Instance checkbox.

  6. Select the variable you created in Step 3 through Step 7 of Section 8.2.1.2, "Adding an Invoke Activity."

  7. Click OK.

    The receive activity and the output variable are created. Because the initial receive activity in the BPEL file (for this example, LoanBroker.bpel) created the initial BPEL process service component instance, a second instance does not need to be created.

8.2.1.4 Performing Additional Activities

In addition to the asynchronous-specific tasks, you must perform the following tasks.

  • Create an initial assign activity for data manipulation in front of the invoke activity that copies the client's input variable loan application request document payload into the loan application approver web service's request variable payload.

  • Create a second assign activity for data manipulation after the receive activity that copies the loan application approver web service's response variable loan application results payload into the output variable for the client to receive.

8.2.2 What Happens When You Invoke an Asynchronous Web Service

This section describes what happens when you invoke an asynchronous web service.

8.2.2.1 portType Section of the WSDL File

The portType section of the WSDL file (in this example, for LoanService) defines the ports to be used for the asynchronous service.

Asynchronous services have two port types. Each port type performs a one-way operation. In this example, one port type responds to the asynchronous process and the other calls back the client with the asynchronous response. In the example shown in Example 8-1, the portType LoanServiceCallback receives the client's loan application request and the portType LoanService asynchronously calls back the client with the loan offer response.

Example 8-1 portType Definition

<!-- portType implemented by the LoanService BPEL process -->
   <portType name="LoanService">
      <operation name="initiate">
         <input message="tns:LoanServiceRequestMessage"/>
      </operation>
   </portType>
<!-- portType implemented by the requester of LoanService BPEL process
for asynchronous callback purposes
-->
   <portType name="LoanServiceCallback">
      <operation name="onResult">
         <input message="tns:LoanServiceResultMessage"/>
      </operation>
   </portType>

8.2.2.2 partnerLinkType Section of the WSDL File

The partnerLinkType section of the WSDL file (in this example, for LoanService) defines the following characteristics of the BPEL process service component:

  • The role (operation) played

  • The portType provided for receiving messages within the conversation

Partner link types in asynchronous services have two roles: one for the web service provider and one for the client requester.

In the conversation shown in Example 8-2, the LoanServiceProvider role and LoanService portType are used for client request messages and the LoanServiceRequester role and LoanServiceCallback portType are used for asynchronously returning (calling back) response messages to the client.

Example 8-2 partnerLinkType Definition

<plnk:partnerLinkType name="LoanService">
        <plnk:role name="LoanServiceProvider">
            <plnk:portType name="client:LoanService"/>
        </plnk:role>
        <plnk:role name="LoanServiceRequester">
            <plnk:portType name="client:LoanServiceCallback"/>
        </plnk:role>
    </plnk:partnerLinkType>

Two port types are combined into this single asynchronous BPEL process service component: portType="services:LoanService" of the invoke activity and portType="services:LoanServiceCallback" of the receive activity. Port types are essentially a collection of operations to be performed. For this BPEL process service component, there are two operations to perform: initiate in the invoke activity and onResult in the receive activity.

8.2.2.3 Partner Links Section in the BPEL File

To call the service from BPEL, you use the BPEL file to define how the process interfaces with the web service. View the partnerLinks section. The services with which a process interacts are designed as partner links. Each partner link is characterized by a partnerLinkType.

Each partner link is named. This name is used for all service interactions through that partner link. This is critical in correlating responses to different partner links for simultaneous requests of the same type.

Asynchronous processes use a second partner link for the callback to the client. In this example, the second partner link, LoanService, is used by the loan application approver web service. Example 8-3 provides an example.

Example 8-3 partnerLink Definition

<!-- This process invokes the asynchronous LoanService. -->

    <partnerLink name="LoanService"
             partnerLinkType="services:LoanService"
             myRole="LoanServiceRequester"
             partnerRole="LoanServiceProvider"/>
  </partnerLinks>

The attribute myRole indicates the role of the client. The attribute partnerRole role indicates the role of the partner in this conversation. Each partnerLinkType has a myRole and partnerRole attribute in asynchronous processes.

8.2.2.4 Composite Application File

In the composite.xml file, the loan application approver web service appears, as shown in Example 8-4.

Example 8-4 Loan Application Approver Web Service

<component name="LoanBroker">
    <implementation.bpel process="LoanBroker.bpel"/>
</component>

For more information, see Section 8.2.1.1, "Adding a Partner Link for an Asynchronous Service" for instructions on creating a partner link.

8.2.2.5 Invoke and Receive Activities

View the variables and sequence sections. Two areas of particular interest concern the invoke and receive activities:

  • An invoke activity invokes a synchronous web service (as discussed in Chapter 7, "Invoking a Synchronous Web Service from a BPEL Process") or initiates an asynchronous service.

    The invoke activity includes the request global input variable defined in the variables section. The request global input variable is used by the loan application approver web service. This variable contains the contents of the initial loan application request document.

  • A receive activity that waits for the asynchronous callback from the loan application approver web service. The receive activity includes the response global output variable defined in the variables section. This variable contains the loan offer response. The receive activity asynchronously waits for a callback message from a service. While the BPEL process service component is waiting, it is dehydrated, or compressed and stored, until the callback message arrives.

Example 8-5 provides an example.

Example 8-5 Invoke and Receive Activities

<variables>

    <variable name="request"
               messageType="services:LoanServiceRequestMessage"/>
    <variable name="response"
               messageType="services:LoanServiceResultMessage"/>
  </variables>

<sequence>


    <!-- initialize the input of LoanService -->
    <assign>
    <!--  initiate the remote process -->
    <invoke name="invoke" partnerLink="LoanService"
        portType="services:LoanService"
        operation="initiate" inputVariable="request"/>

    <!--  receive the result of the remote process -->
    <receive name="receive_invoke" partnerLink="LoanService"
        portType="services:LoanServiceCallback"
        operation="onResult" variable="response"/>

When an asynchronous service is initiated with the invoke activity, a correlation ID unique to the client request is also sent, using Web Services Addressing (WS-Addressing) (described in Section 8.4, "Using WS-Addressing in an Asynchronous Service"). Because multiple processes may be waiting for service callbacks, the server must know which BPEL process service component instance is waiting for a callback message from the loan application approver web service. The correlation ID enables the server to correlate the response with the appropriate requesting instance.

8.2.2.6 createInstance Attribute for Starting a New Instance

You may notice a createInstance attribute in the initial receive activity. In this initial receive activity, the createInstance element is set to yes. This starts a new instance of the BPEL process service component. At least one instance startup is required for a conversation. For this reason, you set the createInstance variable to no in the second receive activity.

Example 8-6 shows the source code for the createInstance attribute:

Example 8-6 createInstance Attribute

<!-- receive input from requester -->
    <receive name="receiveInput" partnerLink="client"
             portType="tns:LoanBroker"
             operation="initiate" variable="input"
             createInstance="yes"/>

8.2.2.7 Dehydration Points for Maintaining Long-Running Asynchronous Processes

To automatically maintain long-running asynchronous processes and their current state information in a database while they wait for asynchronous callbacks, you use a database as a dehydration store. Storing the process in a database preserves the process and prevents any loss of state or reliability if a system shuts down or a network problem occurs. This feature increases both BPEL process service component reliability and scalability. You can also use it to support clustering and failover.

You insert this point between the invoke activity and receive activity. You can also explicitly specify a dehydration point with a dehydrate activity. For more information, see Section A.2.8, "Dehydrate Activity."

8.2.2.8 Multiple Runtime Endpoint Locations

Oracle SOA Suite provides support for specifying multiple partner link endpoint locations. This capability is useful for failover purposes if the first endpoint is down. To provide an alternate partner link endpoint location, add the location attribute to the composite.xml file. Example 8-7 provides an example.

Example 8-7 Alternate Runtime Endpoint Location

<reference name="HeaderService ...>
<binding.ws port="http://services.otn.com/HelloWorldApp#wsdl.endpoint(client/
  HelloWorldService_pt)"
location="http://server:port/soa-infra/services/default/ 
 HelloWorldService!1.0/client?WSDL">
<property name="endpointURI">http://jsmith.us.oracle.com:80/a.jsp 
@http://myhost.us.oracle.com:8888/soa-infra/services/HelloWorldApp/HelloWorld!
1.0*2007-10-22_14-33-04_195/client
 </property>
</binding.ws>
</reference>

8.2.3 What You May Need to Know About Limitations on BPEL 2.0 IMA Support

Receive activities are a type of inbound message activity (IMA). Other examples of IMAs are as follows:

  • onMessage branches of a scope activity (in BPEL 1.1) or a pick activity

  • onEvent branches of a scope activity in BPEL 2.0

The BPEL 2.0 specification allows multiple IMAs to work with each other or with other IMAs derived from extension activities. To provide for consistent runtime behavior, the BPEL 2.0 specification allows for correlation sets with the initiate attribute set to join.However, Oracle BPEL Process Manager's implementation of the BPEL 2.0 specification does not support this behavior. The only way to support multiple IMAs is by coding them as onMessage branches for a pick activity (that is, setting createInstance to yes).Oracle BPEL Process Manager also does not support other forms of multiple IMAs, such as a flow activity with two branches, each with a receive activity and with createInstance set to yes and correlation sets with initiate set to join.

As a workaround, you must design two different BPEL processes with the two receive activities in alternating order, as follows:

  • Process1 with receive1 followed by receive2, and only receive1 having createInstance set to yes

  • Process2 with receive2 followed by receive1, and only receive2 having createInstance set to yes.

The same also applies for any other combination of IMAs, such as a receive activity and pick activity, or two pick activities.

8.2.4 What Happens When You Specify a Conversation ID

You can also enter an optional conversation ID value in the Conversation ID field of an invoke activity (and other activities such as a receive activity and the onMessage branch of a pick or scope activity).

The conversation ID identifies a process instance during an asynchronous conversation. By default, the BPEL process service engine generates a unique ID for each conversation (which can span multiple invoke and receive activities), as specified by WSA addressing. If you want, you can specify your own value for the service engine to use. Conversation IDs are implemented with the bpelx:conversationId extension.

8.2.4.1 bpelx:conversationId in BPEL 1.1

Example 8-8 provides an example of the bpelx:conversationId extension in a BPEL project that supports BPEL version 1.1. The bpelx:conversationId extension takes an XPath expression.

Example 8-8 bpelx:conversationId Conversation ID in BPEL 1.1

<invoke ... bpelx:conversationId="$convId2">
</invoke>

<receive ... bpelx:conversationId="$convId2">
</receive>

<onMessage... bpelx:conversationId="$convId2">
</onMessage>

8.2.4.2 bpelx:conversationId in BPEL 2.0

Example 8-9 provides an example of the bpelx:conversationId extension in a BPEL project that supports BPEL version 2.0. The bpelx:conversationId extension takes a BPEL 2.0 XPath expression.

Example 8-9 bpelx:conversationId Conversation ID in BPEL 2.0

<invoke ...>
  <bpelx:conversationId>$convId1</bpelx:conversationId>
</invoke>

<receive ...>
  <bpelx:conversationId>$convId1</bpelx:conversationId>
</receive>

<onMessage ...>
  <bpelx:conversationId>$convId2</bpelx:conversationId>
</onMessage>

8.3 Using a Dynamic Partner Link at Runtime

You can dynamically configure a partner link at runtime in BPEL. This is useful for scenarios in which the target service that BPEL wants to invoke is not known until runtime.

Note:

Dynamic partner links are only supported in BPEL 1.1 projects.

8.3.1 How To Add and Use a Dynamic Partner Link at Runtime

  1. Create a WSDL file that contains multiple services that use the same portType.

  2. Create a reference binding component entry in the composite.xml file that uses the WSDL:

    <reference name="loanService">
      <interface.wsdl interface="http://services.otn.com#wsdl.interface(LoanService)"
    callbackInterface="http://services.otn.com#wsdl.interface(LoanServiceCallback)"
    />
        <binding.ws port=
           "http://services.otn.com#wsdl.endpoint(AmericanLoan/LoanService_pt)"/>
      </reference>
    

    Notes:

    • Adding the binding.ws port setting is optional. This is because the port is overridden at runtime by properties passed from BPEL.

    • If there is no port setting, and there is no composite import of the concrete WSDL associated with this reference, you must specify the location of the concrete WSDL with a location attribute.

  3. In the BPEL file, programmatically assign the partner link. For this example, UnitedLoan is one of the services defined in the WSDL.

    <copy>
       <from>
         <EndpointReference
            xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing">
    <Address>http://myhost.us.oracle.com:9700/orabpel/default/UnitedLoan</Address>
        </EndpointReference>
       </from>
       <to partnerLink="LoanService"/>
    </copy> 
    

8.4 Using WS-Addressing in an Asynchronous Service

Because there can be many active instances at any time, the server must be able to direct web service responses to the correct BPEL process service component instance. You can use WS-Addressing to identify asynchronous messages to ensure that asynchronous callbacks locate the appropriate client.

Figure 8-3 provides an overview of WS-Addressing. WS-Addressing uses Simple Object Access Protocol (SOAP) headers for asynchronous message correlation. Messages are independent of the transport or application used.

Figure 8-3 Callback with WS-Addressing Headers

Description of Figure 8-3 follows
Description of "Figure 8-3 Callback with WS-Addressing Headers"

Figure 8-3 shows how messages are passed along with WS headers so that the response can be sent to the correct destination.

The example in this chapter uses WS-Addressing for correlation. To view the messages, you can use TCP tunneling, which is described in Section 8.4.1.1, "Using TCP Tunneling to See Messages Exchanged Between Programs."

WS-Addressing defines the following information typically provided by transport protocols and messaging systems. This information is processed independently of the transport or application:

8.4.1 How to Use WS-Addressing in an Asynchronous Service

WS-Addressing is a public specification and is the default correlation method supported by Oracle BPEL Process Manager. You do not need to edit the .bpel and .wsdl files to use WS-Addressing.

8.4.1.1 Using TCP Tunneling to See Messages Exchanged Between Programs

The messages that are exchanged between programs and services can be seen through TCP tunneling. This is particularly useful when you want to see the exact SOAP messages exchanged between the BPEL process service component flow and web services.

To monitor the SOAP messages, insert a software listener between your flow and the service. Your flow communicates with the listener (called a TCP tunnel) and the listener forwards your messages to the service, and displays them. Likewise, responses from the service are returned to the tunnel, which displays them and then forwards them back to the flow.

To see all the messages exchanged between the server and a web service, you need only a single TCP tunnel for synchronous services because all the pertinent messages are communicated in a single request and reply interaction with the service. For asynchronous services, you must set up two tunnels, one for the invocation of the service and another for the callback port of the flow.

8.4.1.1.1 Setting Up a TCP Listener for Synchronous Services

Follow these steps to set up a TCP listener for synchronous services initiated by an Oracle BPEL Process Manager process:

  1. Visit the following URL for instructions on how to download and install Axis TCP Monitor (tcpmon)

    http://ws.apache.org/commons/tcpmon/
    
  2. Visit the following URL for instructions on how to use tcpmon:

    http://ws.apache.org/axis/java/user-guide.html
    
  3. Place axis.jar in your class path.

  4. Start tcpmon:

    C:\...\> java org.apache.axis.utils.tcpmon localport remoteHost
    port_on_which_remote_server_is_running
    
  5. In the composite.xml file, add the endpointURI property under binding.ws for your flow to override the endpoint of the service.

  6. From the operating system command prompt, compile and deploy the process with ant.

    Note that the same technique can see the SOAP messages passed to invoke a BPEL process service component as a web service from another tool kit such as Axis or .NET.

8.4.1.1.2 Setting Up a TCP Listener for Asynchronous Services

Follow these steps to set up a TCP listener to display the SOAP messages for callbacks from asynchronous services:

  1. Start a TCP listener to listen on a port and to send the Oracle BPEL Process Manager port.

    1. Open Oracle Enterprise Manager Fusion Middleware Control.

    2. From the SOA Infrastructure menu, select SOA Administration > Common Properties.

    3. Specify the value for Callback Server URL. This URL is sent by the server as part of the asynchronous callback address to the invoker.

  2. From the SOA Infrastructure menu, select Administration > System MBean Browser.

  3. Expand Application Defined MBeans > oracle.soa.config > Server : soa_server > SCAComposite.

    where soa_server is the specific server instance name (for example, AdminServer).

    All the SOA composite applications deployed on the server appear.

  4. Follow these steps to set this property on a composite application. This action enables it to apply to all bindings in the composite application.

    1. Click your composite.

    2. Ensure the Attributes tab is selected.

    3. In the Name column, click Properties.

    4. Click the Add icon.

    5. Expand the newly added Element_number (appears at the end of the list).

      where number is the next sequential number beyond the last property. For example, if the property list contains twelve elements, adding a new property causes Element_13 to be displayed.

    6. In the name field, enter oracle.webservices.local.optimization.

    7. In the value field, enter false.

    8. In the many field, enter false.

    9. Click Apply, and then click Return.

    10. In the Name column on the Operations tab, click save.

    11. Click Invoke to execute the operation.

    12. Click Return or click a node in the System MBean Browser pane.

      Note:

      After adding, deleting, or updating a property, you can click the Refresh cached tree data icon in the upper right corner of the System MBean Browser page to see the new data.
  5. Follow these steps to set this property on a specific binding.

    1. Expand your composite application. and drill down to the specific SCAComposite.SCAReference.SCABinding folder.

    2. Click WSBinding.

    3. Perform steps 4b through 4l.

  6. Initiate any flow that invokes asynchronous web services. You can combine this with the synchronous TCP tunneling configuration to send a service initiation request through your first TCP tunnel.

    The callbacks from the asynchronous services are shown in the TCP listener.

If you are an Oracle JDeveloper user, you can also use the built-in Packet Monitor to see SOAP messages for both synchronous and asynchronous services.

8.5 Using Correlation Sets in an Asynchronous Service

Correlation sets provide another method for directing web service responses to the correct BPEL process service component instance. You can use correlation sets to identify asynchronous messages to ensure that asynchronous callbacks locate the appropriate client.

Correlation sets are a BPEL mechanism that provides for the correlation of asynchronous messages based on message body contents. To use this method, define the correlation sets in your .bpel file. This method is designed for services that do not support WS-Addressing or for certain sophisticated conversation patterns, for example, when the conversation is in the form A > B > C > A instead of A > B > A.

This section describes how to use correlation sets in an asynchronous service with Oracle JDeveloper. Correlation sets enable you to correlate asynchronous messages based on message body contents. You define correlation sets when interactions are not simple invoke-receive activities. This example illustrates how to use correlation sets for a process having three receive activities with no associated invoke activities.

8.5.1 How to Use Correlation Sets in an Asynchronous Service

This section describes the steps to perform to use correlation sets in an asynchronous service.

8.5.1.1 Step 1: Creating a Project

To create a project:

  1. Start Oracle JDeveloper.

  2. From the File main menu, select New > Applications.

  3. Select SOA Application, and click OK.

    The Create SOA Application Wizard appears.

  4. In the Application Name field, enter MyCorrelationSetApp.

  5. Accept the default values for all remaining settings, and click Next.

  6. In the Project Name field, enter MyCorrelationSetComposite.

  7. Accept the default values for all remaining settings, and click Next.

  8. In the Composite Template section, select Composite With BPEL Process, and click Finish.

    The Create BPEL Process dialog appears.

  9. Enter the values shown in Table 8-1.

    Table 8-1 Create BPEL Process Dialog Fields and Values

    Field Value

    Name

    Enter MyCorrelationSet.

    Template

    Select Asynchronous BPEL Process.

    Expose as a SOAP Service

    Select the checkbox. After process creation, note the SOAP service that appears in the Exposed Services swimlane. This service provides the entry point to the composite application from the outside world.


  10. Accept the default values for all remaining settings, and click OK.

8.5.1.2 Step 2: Configuring Partner Links and File Adapter Services

You now create three partner links that use the SOAP service.

This section contains these topics:

  • You create an initial partner link with an adapter service for reading a loan application.

  • You create a second partner link with an adapter service for reading an application response.

  • You create a third partner link with an adapter service for reading a customer response.

8.5.1.2.1 Creating an Initial Partner Link and File Adapter Service

To create an initial partner link and file adapter service:

  1. Double-click the MyCorrelationSet BPEL process.

  2. In the Component Palette, expand BPEL Constructs.

  3. Drag an initial Partner Link activity into the right swimlane of the designer.

  4. Click the third icon at the top (the Service Wizard icon). This starts the Adapter Configuration Wizard, as shown in Figure 8-4.

    Figure 8-4 Adapter Configuration Wizard Startup

    Description of Figure 8-4 follows
    Description of "Figure 8-4 Adapter Configuration Wizard Startup"

  5. In the Configure Service or Adapter dialog, select File Adapter and click OK.

  6. In the Welcome dialog, click Next.

  7. In the Service Name field of the Service Name dialog, enter FirstReceive and click Next.

  8. In the Adapter Interface dialog, accept the default settings and click Next.

  9. In the Operation dialog, select Read File as the Operation Type and click Next. The Operation Name field is automatically filled in with Read.

  10. Above the Directory for Incoming Files (physical path) field, click Browse.

  11. Select a directory from which to read files (for this example, C:\files\receiveprocess\FirstInputDir is selected).

  12. Click Select.

  13. Click Next.

  14. In the File Filtering dialog, enter appropriate file filtering parameters.

  15. Click Next.

  16. In the File Polling dialog, enter appropriate file polling parameters.

  17. Click Next.

  18. In the Messages dialog, click Browse next to the URL field to display the Type Chooser dialog.

  19. Select an appropriate XSD schema file. For this example, Book1_4.xsd is the schema and LoanAppl is the schema element selected.

  20. Click OK.

    The URL field (Book1_4.xsd for this example) and the Schema Element field (LoanAppl for this example) are filled in.

  21. Click Next.

  22. Click Finish.

    You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 8-2:

    Table 8-2 Partner Link Dialog Fields and Values

    Field Value

    Name

    FirstReceive

    WSDL URL

    directory_path/FirstReceive.wsdl

    Partner Link Type

    Read_plt

    Partner Role

    Leave unspecified.

    My Role

    Read_role


  23. Click OK.

8.5.1.2.2 Creating a Second Partner Link and File Adapter Service

To create a second partner link and file adapter service:

  1. Drag a second PartnerLink activity beneath the FirstReceive partner link activity.

  2. At the top, click the third icon (the Service Wizard icon).

  3. In the Configure Service or Adapter dialog, select File Adapter and click OK.

  4. In the Welcome dialog, click Next.

  5. In the Adapter Type dialog, select File Adapter and click Next.

  6. In the Service Name field of the Service Name dialog, enter SecondFileRead and click Next. This name must be unique from the one you entered in Step 7 of Section 8.5.1.2.1, "Creating an Initial Partner Link and File Adapter Service."

  7. In the Adapter Interface dialog, accept the default settings and click Next.

  8. In the Operation dialog, select Read File as the Operation Type.

  9. In the Operation Name field, change the name to Read1.

  10. Click Next.

  11. Select Directory Names are Specified as Physical Path.

  12. Above the Directory for Incoming Files (physical path) field, click Browse.

  13. Select a directory from which to read files (for this example, C:\files\receiveprocess\SecondInputDir is entered).

  14. Click Select.

  15. Click Next.

  16. Enter appropriate file filtering parameters in the File Filtering dialog.

  17. Click Next.

  18. Enter appropriate file polling parameters in the File Polling dialog.

  19. Click Next.

  20. Next to the URL field in the Messages dialog, click Browse to display the Type Chooser dialog.

  21. Select an appropriate XSD schema file. For this example, Book1_5.xsd is the schema and LoanAppResponse is the schema element selected.

  22. Click OK.

    The URL field (Book1_5.xsd for this example) and the Schema Element field (LoanAppResponse for this example) are filled in.

  23. Click Next.

  24. Click Finish.

    You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 8-3:

    Table 8-3 Partner Link Dialog Fields and Values

    Field Value

    Name

    SecondReceive

    WSDL URL

    directory_path/SecondFileRead.wsdl

    Partner Link Type

    Read1_plt

    Partner Role

    Leave unspecified.

    My Role

    Read1_role


  25. Click OK.

8.5.1.2.3 Creating a Third Partner Link and File Adapter Service

To create a third partner link and file adapter service:

  1. Drag a third PartnerLink activity beneath the SecondReceive partner link activity.

  2. At the top, click the third icon (the Service Wizard icon).

  3. In the Configure Service or Adapter dialog, select File Adapter and click OK.

  4. In the Welcome dialog, click Next.

  5. In the Adapter Type dialog, select File Adapter and click Next.

  6. In the Service Name field of the Service Name dialog, enter ThirdFileRead and click Next. This name must be unique from the one you entered in Step 7 and Step 6 of Section 8.5.1.2.2, "Creating a Second Partner Link and File Adapter Service."

  7. In the Adapter Interface dialog, accept the default settings and click Next.

  8. In the Operation dialog, select Read File as the Operation Type.

  9. In the Operation Name field, change the name to Read2. This name must be unique.

  10. Click Next.

  11. Select Directory Names are Specified as Physical Path.

  12. Above the Directory for Incoming Files (physical path) field, click Browse.

  13. Select a directory from which to read files (for this example, C:\files\receiveprocess\ThirdInputDir is entered).

  14. Click Select.

  15. Click Next.

  16. Enter appropriate file filtering parameters in the File Filtering dialog.

  17. Click Next.

  18. Enter appropriate file polling parameters in the File Polling dialog.

  19. Click Next.

  20. Next to the URL field in the Messages dialog, click Browse to display the Type Chooser dialog.

  21. Select an appropriate XSD schema file. For this example, Book1_6.xsd is the schema and CustResponse is the schema element selected.

  22. Click OK.

    The URL field (Book1_6.xsd for this example) and the Schema Element field (CustResponse for this example) are filled in.

  23. Click Next.

  24. Click Finish.

    You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 8-4:

    Table 8-4 Partner Link Dialog Fields and Values

    Field Value

    Name

    ThirdReceive

    WSDL URL

    directory_path/ThirdFileRead.wsdl

    Partner Link Type

    Read2_plt

    Partner Role

    Leave unspecified.

    My Role

    Read2_role


  25. Click OK.

8.5.1.3 Step 3: Creating Three Receive Activities

You now create three receive activities; one for each partner link. The receive activities specify the partner link from which to receive information.

8.5.1.3.1 Creating an Initial Receive Activity

To create an initial receive activity:

  1. Expand BPEL Constructs in the Component Palette.

  2. Drag a Receive activity beneath the receiveInput receive activity in the designer.

  3. Double-click the receive icon to display the Receive dialog.

  4. Enter the details described in Table 8-5 to associate the first partner link (FirstReceive) with the first receive activity:

    Table 8-5 Receive Dialog Fields and Values

    Field Value

    Name

    receiveFirst

    Partner Link

    FirstReceive

    Create Instance

    Select this checkbox.


    The Operation (Read) field is automatically filled in.

  5. To the right of the Variable field, click the first icon. This is the automatic variable creation icon.

  6. In the Create Variable dialog, click OK.

    A variable named receiveFirst_Read_InputVariable is automatically created in the Variable field.

  7. Ensure that you selected the Create Instance checkbox, as mentioned in Step 4.

  8. Click OK.

8.5.1.3.2 Creating a Second Receive Activity

To create a second receive activity:

  1. From the Component Palette, drag a second Receive activity beneath the receiveFirst receive activity.

  2. Double-click the receive icon to display the Receive dialog.

  3. Enter the details described in Table 8-6 to associate the second partner link (SecondReceive) with the second receive activity:

    Table 8-6 Receive Dialog Fields and Values

    Field Value

    Name

    receiveSecond

    Partner Link

    SecondFileRead

    Create Instance

    Do not select this checkbox.


    The Operation (Read1) field is automatically filled in.

  4. To the right of the Variable field, click the first icon.

  5. In the Create Variable dialog, click OK.

    A variable named receiveSecond_Read1_InputVariable is automatically created in the Variable field.

  6. Click OK.

8.5.1.3.3 Creating a Third Receive Activity

To create a third receive activity:

  1. From the Component Palette, drag a third Receive activity beneath the receiveSecond receive activity.

  2. Double-click the receive icon to display the Receive dialog.

  3. Enter the details described in Table 8-7 to associate the third partner link (ThirdReceive) with the third receive activity:

    Table 8-7 Receive Dialog Fields and Values

    Field Value

    Name

    receiveThird

    Partner Link

    ThirdFileRead

    Create Instance

    Do not select this checkbox.


    The Operation (Read2) field is automatically filled in.

  4. To the right of the Variable field, click the first icon.

  5. In the Create Variable dialog, click OK.

    A variable named receiveThird_Read2_InputVariable is automatically created in the Variable field.

  6. Click OK.

    Each receive activity is now associated with a specific partner link.

8.5.1.4 Step 4: Creating Correlation Sets

You now create correlation sets. A set of correlation tokens is a set of properties shared by all messages in the correlated group.

8.5.1.4.1 Creating an Initial Correlation Set

To create an initial correlation set:

  1. In the Structure window of Oracle JDeveloper, right-click Correlation Sets and select Expand All Child Nodes.

  2. In the second Correlation Sets folder, right-click and select Create Correlation Set.

  3. In the Name field of the Create Correlation Set dialog, enter CorrelationSet1.

  4. In the Properties section, click the Add icon to display the Property Chooser dialog.

  5. Select Properties, then click the Add icon (first icon at the top) to display the Create Property dialog.

  6. In the Name field, enter NameCorr.

  7. To the right of the Type field, click the Browse icon.

  8. In the Type Chooser dialog, select string and click OK.

  9. Click OK to close the Create Property dialog, the Property Chooser dialog, and the Create Correlation Set dialog.

8.5.1.4.2 Creating a Second Correlation Set

To create a second correlation set:

  1. Return to the Correlation Sets section in the Structure window of Oracle JDeveloper.

  2. Right-click the Correlation Sets folder and select Create Correlation Set.

  3. In the Name field of the Create Correlation Set dialog, enter CorrelationSet2.

  4. In the Properties section, click the Add icon to display the Property Chooser dialog.

  5. Select Properties, then click the Add icon to display the Create Property dialog.

  6. In the Name field, enter IDCorr.

  7. To the right of the Type field, click the Browse icon.

  8. In the Type Chooser dialog, select double and click OK.

  9. Click OK to close the Create Property dialog, the Property Chooser dialog, and the Create Correlation Set dialog.

8.5.1.5 Step 5: Associating Correlation Sets with Receive Activities

You now associate the correlation sets with the receive activities. You perform the following correlation set tasks:

  • For the first correlated group, the first and second receive activities are correlated with the CorrelationSet1 correlation set.

  • For the second correlated group, the second and third receive activities are correlated with the CorrelationSet2 correlation set.

8.5.1.5.1 Associating the First Correlation Set with a Receive Activity

To associate the first correlation set with a receive activity:

  1. Double-click the receiveFirst receive activity to display the Receive dialog.

  2. Click the Correlations tab.

  3. Click the Add icon to display the correlation set dropdown list.

  4. Select CorrelationSet1.

  5. Click the Initiate column to display a dropdown list, and select yes. When set to yes, the set is initiated with the values of the properties occurring in the message being exchanged.

  6. Click OK.

8.5.1.5.2 Associating the Second Correlation Set with a Receive Activity

To associate the second correlation set with a receive activity:

  1. Double-click the receiveSecond receive activity to display the Receive dialog.

  2. Click the Correlations tab.

  3. Click the Add icon to display the correlation set dropdown list.

  4. Select CorrelationSet2, then click OK.

  5. Click the Initiate column to display a dropdown list, and select yes.

  6. Click Add again and select CorrelationSet1.

  7. Click OK.

  8. Click the Initiate column to display a dropdown list, and select no for CorrelationSet1.

  9. Click OK.

    This groups the first and second receive activities into a correlated group.

8.5.1.5.3 Associating the Third Correlation Set with a Receive Activity

To associate the third correlation set with a receive activity:

  1. Double-click the receiveThird receive activity to display the Receive dialog.

  2. Click the Correlations tab.

  3. Click the Add icon.

  4. Select CorrelationSet2.

  5. Set the Initiate column to no for CorrelationSet2.

  6. Click OK.

    This groups the second and third receive activities into a second correlated group.

8.5.1.6 Step 6: Creating Property Aliases

Property aliases enable you to map a global property to a field in a specific message part. This action enables the property name to become an alias for the message part and location. The alias can be used in XPath expressions.

8.5.1.6.1 Creating Property Aliases for NameCorr

You create the following two property aliases for the NameCorr correlation set:

  • Map NameCorr to the LoanAppl message type part of the receiveFirst receive activity. This receive activity is associated with the FirstReceive partner link (defined by the FirstReceive.wsdl file).

  • Map NameCorr to the incoming LoanAppResponse message type part of the receiveSecond receive activity. This receive activity is associated with the SecondReceive partner link (defined by the SecondFileRead.wsdl file).

To create property aliases for NameCorr:

  1. In the Structure window of Oracle JDeveloper, right-click Property Aliases.

  2. Select Create Property Alias.

  3. From the Property list, select NameCorr.

  4. Expand and select Message Types > Partner Link > FirstReceive > FirstReceive.wsdl > Message Types > LoanAppl_msg > Part - LoanAppl.

  5. In the Query field, press Ctrl+Space to define the following XPath expression:

    /ns2:LoanAppl/ns2:Name
    
  6. Click OK.

  7. Repeat Step 1 through Step 3 to create a second property alias for NameCorr.

  8. Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.

  9. In the Query field, press Ctrl+Space to define the following XPath expression:

    /ns4:LoanAppResponse/ns4:APR
    
  10. Click OK.

8.5.1.6.2 Creating Property Aliases for IDCorr

You create the following two property aliases for the IDCorr correlation set:

  • Map IDCorr to the LoanAppResponse message type part of the receiveSecond receive activity. This receive activity is associated with the SecondReceive partner link (defined by the SecondFileRead.wsdl file).

  • Map IDCorr to the CustResponse message type part of the receiveThird receive activity. This receive activity is associated with the ThirdReceive partner link (defined by the ThirdFileRead.wsdl file).

To create property aliases for IDCorr:

  1. In the Structure window, right-click Property Aliases.

  2. Select Create Property Alias.

  3. In the Property list, select IDCorr.

  4. Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.

  5. In the Query field, press Ctrl+Space to define the following XPath expression:

    /ns4:LoanAppResponse/ns4:APR
    
  6. Click OK.

  7. Repeat Step 1 through Step 3 to create a second property alias for IDCorr.

  8. Expand and select Message Types > Project WSDL Files > ThirdFileRead.wsdl > Message Types > CustResponse_msg > Part - CustResponse.

  9. In the Query field, press Ctrl+Space to define the following XPath expression:

    /ns6:CustResponse/ns6:APR
    

    Design is now complete.

  10. Click OK.

8.5.1.7 Step 7: Reviewing WSDL File Content

To review WSDL file content:

  1. Refresh the Application Navigator.

    The NameCorr and IDCorr correlation set properties are defined in the MyCorrelationSet_Properties.wsdl file in the Application Navigator. Example 8-10 provides an example.

    Example 8-10 Correlation Set Properties

    <definitions
         name="properties"
         targetNamespace="http://xmlns.oracle.com/MyCorrelationSet/correlationset"
         xmlns="http://schemas.xmlsoap.org/wsdl/"
         xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
         xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <bpws:property name="NameCorr" type="xsd:string"/>
        <bpws:property name="IDCorr" type="xsd:double"/>
    </definitions>
    

    The property aliases are defined in the MyCorrelationSet.wsdl file, as shown in Example 8-11:

    Example 8-11 Property Aliases

    <bpws:propertyAlias propertyName="ns1:NameCorr"
     messageType="ns3:LoanAppl_msg"
     part="LoanAppl" query="/ns2:LoanAppl/ns2:Name"/>
    
    <bpws:propertyAlias propertyName="ns1:NameCorr" 
     messageType="ns5:LoanAppResponse_msg" 
     part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>
    
    <bpws:propertyAlias propertyName="ns1:IDCorr" 
     messageType="ns5:LoanAppResponse_msg" 
     part="LoanAppResponse" query="/ns4:LoanAppResponse/ns4:APR"/>
    
    <bpws:propertyAlias propertyName="ns1:IDCorr" 
     messageType="ns7:CustResponse_msg" 
     part="CustResponse" query="/ns6:CustResponse/ns6:APR"/>
    

    Because the BPEL process service component is not created as a web services provider in this example, the MyCorrelationSet.wsdl file is not referenced in the BPEL process service component. Therefore, you must import the MyCorrelationSet.wsdl file inside the FirstReceive.wsdl file to reference the correlation sets defined in the former WSDL. Example 8-12 provides an example.

    Example 8-12 WSDL File Import

    <import namespace="http://xmlns.oracle.com/MyCorrelationSet"
     location="MyCorrelationSet.wsdl"/>
    

8.5.2 What You May Need to Know About Setting Correlations for an IMA Using a fromParts Element With Multiple Parts

Assume you have the following scenario:

  • A BPEL 2.0 process with a WSDL message type that has multiple parts that are identical in type.

  • A property alias has been defined based on the element type of the above part.

For a process that has an inbound message activity (IMA) (for example, a receive activity, onMessage branch of a scope or pick activity, or onEvent branch of a scope activity in BPEL 2.0) that uses the fromParts element with fromPart defined for each part, correlations cannot be defined because the runtime environment cannot determine the part to which to apply the property alias.

For more information about mapping WSDL message parts with the toParts and fromParts elements, see Section 6.17, "Mapping WSDL Message Parts in BPEL 2.0."