Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1.6.0) Part Number E10224-11 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use correlation sets to ensure that asynchronous callbacks locate the appropriate client. It also describes how to use aggregation patterns to route messages to the same instance.
This chapter includes the following sections:
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.
This section describes the steps to perform to use correlation sets in an asynchronous service.
To create a project:
Start Oracle JDeveloper.
From the File main menu, select New > Applications.
Select SOA Application, and click OK.
The Create SOA Application Wizard appears.
In the Application Name field, enter MyCorrelationSetApp
.
Accept the default values for all remaining settings, and click Next.
In the Project Name field, enter MyCorrelationSetComposite
.
Accept the default values for all remaining settings, and click Next.
In the Composite Template section, select Composite With BPEL Process, and click Finish.
The Create BPEL Process dialog appears.
Enter the values shown in Table 9-1.
Table 9-1 Create BPEL Process Dialog Fields and Values
Field | Value |
---|---|
Name |
Enter |
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. |
Accept the default values for all remaining settings, and click OK.
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.
To create an initial partner link and file adapter service:
Double-click the MyCorrelationSet BPEL process.
In the Component Palette, expand BPEL Constructs.
Drag an initial Partner Link activity into the right swimlane of the designer.
Click the third icon at the top (the Service Wizard icon). This starts the Adapter Configuration Wizard, as shown in Figure 9-1.
Figure 9-1 Adapter Configuration Wizard Startup
In the Configure Service or Adapter dialog, select File Adapter and click OK.
In the Welcome dialog, click Next.
In the Service Name field of the Service Name dialog, enter FirstReceive
and click Next.
In the Adapter Interface dialog, accept the default settings and click Next.
In the Operation dialog, select Read File as the Operation Type and click Next. The Operation Name field is automatically filled in with Read.
Above the Directory for Incoming Files (physical path) field, click Browse.
Select a directory from which to read files (for this example, C:\files\receiveprocess\FirstInputDir is selected).
Click Select.
Click Next.
In the File Filtering dialog, enter appropriate file filtering parameters.
Click Next.
In the File Polling dialog, enter appropriate file polling parameters.
Click Next.
In the Messages dialog, click Browse next to the URL field to display the Type Chooser dialog.
Select an appropriate XSD schema file. For this example, Book1_4.xsd is the schema and LoanAppl is the schema element selected.
Click OK.
The URL field (Book1_4.xsd for this example) and the Schema Element field (LoanAppl for this example) are filled in.
Click Next.
Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 9-2:
Click OK.
To create a second partner link and file adapter service:
Drag a second PartnerLink activity beneath the FirstReceive partner link activity.
At the top, click the third icon (the Service Wizard icon).
In the Configure Service or Adapter dialog, select File Adapter and click OK.
In the Welcome dialog, click Next.
In the Adapter Type dialog, select File Adapter and click Next.
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 9.1.1.2.1, "Creating an Initial Partner Link and File Adapter Service."
In the Adapter Interface dialog, accept the default settings and click Next.
In the Operation dialog, select Read File as the Operation Type.
In the Operation Name field, change the name to Read1
.
Click Next.
Select Directory Names are Specified as Physical Path.
Above the Directory for Incoming Files (physical path) field, click Browse.
Select a directory from which to read files (for this example, C:\files\receiveprocess\SecondInputDir is entered).
Click Select.
Click Next.
Enter appropriate file filtering parameters in the File Filtering dialog.
Click Next.
Enter appropriate file polling parameters in the File Polling dialog.
Click Next.
Next to the URL field in the Messages dialog, click Browse to display the Type Chooser dialog.
Select an appropriate XSD schema file. For this example, Book1_5.xsd is the schema and LoanAppResponse is the schema element selected.
Click OK.
The URL field (Book1_5.xsd for this example) and the Schema Element field (LoanAppResponse for this example) are filled in.
Click Next.
Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 9-3:
Click OK.
To create a third partner link and file adapter service:
Drag a third PartnerLink activity beneath the SecondReceive partner link activity.
At the top, click the third icon (the Service Wizard icon).
In the Configure Service or Adapter dialog, select File Adapter and click OK.
In the Welcome dialog, click Next.
In the Adapter Type dialog, select File Adapter and click Next.
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 of Section 9.1.1.2.1, "Creating an Initial Partner Link and File Adapter Service" and Step 6 of Section 9.1.1.2.2, "Creating a Second Partner Link and File Adapter Service."
In the Adapter Interface dialog, accept the default settings and click Next.
In the Operation dialog, select Read File as the Operation Type.
In the Operation Name field, change the name to Read2
. This name must be unique.
Click Next.
Select Directory Names are Specified as Physical Path.
Above the Directory for Incoming Files (physical path) field, click Browse.
Select a directory from which to read files (for this example, C:\files\receiveprocess\ThirdInputDir is entered).
Click Select.
Click Next.
Enter appropriate file filtering parameters in the File Filtering dialog.
Click Next.
Enter appropriate file polling parameters in the File Polling dialog.
Click Next.
Next to the URL field in the Messages dialog, click Browse to display the Type Chooser dialog.
Select an appropriate XSD schema file. For this example, Book1_6.xsd is the schema and CustResponse is the schema element selected.
Click OK.
The URL field (Book1_6.xsd for this example) and the Schema Element field (CustResponse for this example) are filled in.
Click Next.
Click Finish.
You are returned to the Partner Link dialog. All other fields are automatically completed. The dialog looks as shown in Table 9-4:
Click OK.
You now create three receive activities; one for each partner link. The receive activities specify the partner link from which to receive information.
To create an initial receive activity:
Expand BPEL Constructs in the Component Palette.
Drag a Receive activity beneath the receiveInput receive activity in the designer.
Double-click the receive icon to display the Receive dialog.
Enter the details described in Table 9-5 to associate the first partner link (FirstReceive) with the first receive activity:
Table 9-5 Receive Dialog Fields and Values
Field | Value |
---|---|
Name |
|
Partner Link |
FirstReceive |
Create Instance |
Select this checkbox. |
The Operation (Read) field is automatically filled in.
To the right of the Variable field, click the first icon. This is the automatic variable creation icon.
In the Create Variable dialog, click OK.
A variable named receiveFirst_Read_InputVariable is automatically created in the Variable field.
Ensure that you selected the Create Instance checkbox, as mentioned in Step 4.
Click OK.
To create a second receive activity:
From the Component Palette, drag a second Receive activity beneath the receiveFirst receive activity.
Double-click the receive icon to display the Receive dialog.
Enter the details described in Table 9-6 to associate the second partner link (SecondReceive) with the second receive activity:
Table 9-6 Receive Dialog Fields and Values
Field | Value |
---|---|
Name |
|
Partner Link |
SecondFileRead |
Create Instance |
Do not select this checkbox. |
The Operation (Read1) field is automatically filled in.
To the right of the Variable field, click the first icon.
In the Create Variable dialog, click OK.
A variable named receiveSecond_Read1_InputVariable is automatically created in the Variable field.
Click OK.
To create a third receive activity:
From the Component Palette, drag a third Receive activity beneath the receiveSecond receive activity.
Double-click the receive icon to display the Receive dialog.
Enter the details described in Table 9-7 to associate the third partner link (ThirdReceive) with the third receive activity:
Table 9-7 Receive Dialog Fields and Values
Field | Value |
---|---|
Name |
|
Partner Link |
ThirdFileRead |
Create Instance |
Do not select this checkbox. |
The Operation (Read2) field is automatically filled in.
To the right of the Variable field, click the first icon.
In the Create Variable dialog, click OK.
A variable named receiveThird_Read2_InputVariable is automatically created in the Variable field.
Click OK.
Each receive activity is now associated with a specific partner link.
You now create correlation sets. A set of correlation tokens is a set of properties shared by all messages in the correlated group.
To create an initial correlation set:
In the Structure window of Oracle JDeveloper, right-click Correlation Sets and select Expand All Child Nodes.
In the second Correlation Sets folder, right-click and select Create Correlation Set.
In the Name field of the Create Correlation Set dialog, enter CorrelationSet1
.
In the Properties section, click the Add icon to display the Property Chooser dialog.
Select Properties, then click the Add icon (first icon at the top) to display the Create Property dialog.
In the Name field, enter NameCorr
.
To the right of the Type field, click the Browse icon.
In the Type Chooser dialog, select string and click OK.
Click OK to close the Create Property dialog, the Property Chooser dialog, and the Create Correlation Set dialog.
To create a second correlation set:
Return to the Correlation Sets section in the Structure window of Oracle JDeveloper.
Right-click the Correlation Sets folder and select Create Correlation Set.
In the Name field of the Create Correlation Set dialog, enter CorrelationSet2
.
In the Properties section, click the Add icon to display the Property Chooser dialog.
Select Properties, then click the Add icon to display the Create Property dialog.
In the Name field, enter IDCorr
.
To the right of the Type field, click the Browse icon.
In the Type Chooser dialog, select double and click OK.
Click OK to close the Create Property dialog, the Property Chooser dialog, and the Create Correlation Set dialog.
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.
To associate the first correlation set with a receive activity:
Double-click the receiveFirst receive activity to display the Receive dialog.
Click the Add icon to display the correlation set dropdown list.
Select CorrelationSet1.
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.
Click OK.
To associate the second correlation set with a receive activity:
Double-click the receiveSecond receive activity to display the Receive dialog.
Click the Add icon to display the correlation set dropdown list.
Select CorrelationSet2, then click OK.
Click the Initiate column to display a dropdown list, and select yes.
Click Add again and select CorrelationSet1.
Click OK.
Click the Initiate column to display a dropdown list, and select no for CorrelationSet1.
Click OK.
This groups the first and second receive activities into a correlated group.
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.
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:
In the Structure window of Oracle JDeveloper, right-click Property Aliases.
Select Create Property Alias.
From the Property list, select NameCorr.
Expand and select Message Types > Partner Link > FirstReceive > FirstReceive.wsdl > Message Types > LoanAppl_msg > Part - LoanAppl.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns2:LoanAppl/ns2:Name
Click OK.
Repeat Step 1 through Step 3 to create a second property alias for NameCorr.
Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns4:LoanAppResponse/ns4:APR
Click OK.
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:
In the Structure window, right-click Property Aliases.
Select Create Property Alias.
In the Property list, select IDCorr.
Expand and select Message Types > Project WSDL Files > SecondFileRead.wsdl > Message Types > LoanAppResponse_msg > Part - LoanAppResponse.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns4:LoanAppResponse/ns4:APR
Click OK.
Repeat Step 1 through Step 3 to create a second property alias for IDCorr.
Expand and select Message Types > Project WSDL Files > ThirdFileRead.wsdl > Message Types > CustResponse_msg > Part - CustResponse.
In the Query field, press Ctrl+Space to define the following XPath expression:
/ns6:CustResponse/ns6:APR
Design is now complete.
Click OK.
To review WSDL file content:
Refresh the Application Navigator.
The NameCorr
and IDCorr
correlation set properties are defined in the MyCorrelationSet_Properties.wsd
l
file in the Application Navigator. Example 9-1 provides an example.
Example 9-1 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 9-2:
Example 9-2 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 9-3 provides an example.
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."
Oracle BPEL Process Manager supports a message aggregation feature. When multiple messages are routed to the same process/partner link/operation name, the first message is routed to create a new instance and subsequent messages can be routed to continue the created instance using a midprocess receive activity.
Message aggregation enables you to use the same operation (or event name) in an entry receive activity and a midprocess receive activity.
Notes:
This feature only performs aggregation, and not resequencing. This feature does not resequence messages arriving out of order into an ordered format. Therefore, the first message only means the first message processed. This may be different from the first message in a time sequence order.
You must use correlation sets to take advantage of the message aggregation feature.
Synchronous operations as ambiguous calls (at both beginning and midprocess receive activities) are supported. However, this is not a recommended use of this feature and should be avoided.
You can control the number of instances to create and use to route messages with the reenableAggregationOnComplete
property.
To configure BPEL process instance creation:
In the SOA Composite Editor, select the BPEL process service component, as shown in Figure 9-2.
Figure 9-2 Selected BPEL Process Service Component
Go to the Property Inspector in the lower right corner of Oracle JDeveloper. If the Property Inspector is not displayed, select Property Inspector from the View main menu.
In the Properties section, click the Add icon, as shown in Figure 9-3.
The Create Property dialog is displayed.
In the Name field, enter the bpel.config.reenableAggregationOnComplete
deployment descriptor property. The prefix of bpel.config
is required for this type of deployment descriptor.
In the Value field, enter true
, as described in Table 9-8.
Table 9-8 reenableAggregationOnComplete Property Settings
Value | Description | Example |
---|---|---|
|
Creates a new instance to handle messages. However, there is a window between messages coming in and instance completion. This can result in messages remaining in the |
You invoke messages 1 through 4 for a client using the
|
|
This is the default behavior. This setting causes the aggregation feature to be disabled. Only one instance is created. Messages that are not handled by the instance remain in the |
You invoke messages 1 through 4 for a client using the You should not attempt to route multiple messages using the same correlation set to one BPEL instance. |
Figure 9-4 shows the completed Create Property dialog.
Click OK.
Example 9-4 shows the reenableAggregationOnComplete
property with the bpel.config
prefix in the composite.xml
file.
Example 9-4 reenableAggregationOnComplete Property in composite.xml File
<composite name="Aggregation" revision="1.0" label="2011-07-10_13-52-24_174" mode="active" state="on"> . . . . . . <component name="Aggregation" version="1.1"> <implementation.bpel src="Aggregation.bpel"/> <property name="bpel.config.reenableAggregationOnComplete" type="xs:string" many="false" override="may">true</property> </component> . . . . . . </composite>
You create a correlation set as shown in Example 9-5. All messages to Oracle BPEL Process Manager are routed to the same operation name. The messages have the same correlation ID. The interface WSDL does not differentiate between the entry activity (receiveInput
) and the midprocess receive activity (Continue_Receive
). All messages are processed using the initiate
operation. A single instance is created to which to route all messages.
This differs from releases before 11g Release 1 11.1.1.6, in which you needed to define different operation names on the same partner link. The process had to expose two operations and the caller had to choose the correct operation name.
Example 9-5 Correlation with Same Operation in Entry and Midprocess Receive Activities
<receive name="receiveInput" partnerLink="client" portType="client:BPELProcess1" operation="initiate" variable="inputVariable" createInstance="yes"> <correlations> <correlation initiate="yes" set="CorrelationSet_1"/> </correlations> </receive> <!-- Asynchronous callback to the requester. (Note: the callback location and correlation id is transparently handled using WS-addressing.) --> <assign name="Assign_1"> <copy> <from variable="inputVariable" part="payload" query="/client:BPELProcess1ProcessRequest/client:input"/> <to variable="Invoke_1_initiate_InputVariable" part="payload" query="/ns1:BPELProcess2ProcessRequest/ns1:input"/> </copy> </assign> <receive name="Continue_Receive" partnerLink="client" portType="client:BPELProcess1" operation="initiate" variable="inputVariable" createInstance="no"> <correlations> <correlation initiate="no" set="CorrelationSet_1"/> </correlations> </receive>
For event delivery network (EDN) business events, you substitute the operation
attribute with bpelx:eventName
in both the entry and midprocess receive activities.
bpelx:eventName="ns3:initiateEvent"/>
Information is maintained in the DLV_AGGREGATION
table:
Conversation ID
Domain name
Component name and type
Composite name, label, and revision
State
Received date
CI key
Primary key
This information can be deleted from this table with the purge scripts or from the Delete With Options dialog in Oracle Enterprise Manager Fusion Middleware Control. For more information about both of these options, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
For a BPEL process using correlation sets, the correct routing is performed. The message can be either of the following:
An invoke message creating a new instance
A callback message continuing an existing instance
Example 9-6 provides an example of entry and midprocess receive activities using the same operation (process
).
Example 9-6 Routing a New Message to a New or Existing Instance
<receive name="receiveInput" partnerLink="client" portType="client:BPELProcess1" operation="process" variable="inputVariable" createInstance="yes"> <correlations> <correlation initiate="yes" set="CorrelationSet_1"/> </correlations> </receive> <!-- some business logic --> <while name="While_1" condition=*loop for 3 iterations*> <sequence name="Sequence_1"> <receive name="Continue_Receive" partnerLink="client" portType="client:BPELProcess1" operation="process" variable="inputVariable" createInstance="no"> <correlations> <correlation initiate="no" set="CorrelationSet_1"/> </correlations> </receive> <!-- some business logic --> </sequence> </while>
In the initial scenario in Example 9-6, the following actions occur in BPEL process P1:
A partner provides four messages (message 1, message 2, message 3, and message 4) for the same partner (correlation ID 101
).
Message 1 creates a new instance of BPEL process P1. This message is marked as an invoke message.
Messages 2, 3, and 4 are received using the Continue_Receive
activity. These messages are marked as callback messages.
The instance closes because three iterations of the while
loop are expected.
Assume now that additional messages are routed, which can potentially cause race conditions to occur. Table 9-9 provides details.
Table 9-9 Message Delivery Scenarios
Scenario | Description | Marked as Invoke Message | Marked as Callback Message |
---|---|---|---|
1 |
Assume the partner now provides message 5 for the same correlation ID ( |
|
|
2 |
If messages 4 and 5 are received within a small time window, it is possible that message 4 is closing the instance BPEL process P1 and message 5 is routed as a callback to that instance. This scenario can cause a race condition. For example:
|
|
|
3 |
This is similar to scenario 2. However, in this case, messages 7, 8, and 9 are not received. For example:
There are several options for message recovery.
|
|
|