| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
When to implement: When updates created in a SOA composite application need to perform create, read, update, or delete (CRUD) operations on back-end data stored in a database.
Design Pattern Summary: Entity variables within a BPEL process service component access ADF Business Components view objects through a service to fetch data on the back end. The BPEL process service component then manipulates the data, and the changes synchronize with the ADF Business Components service when the BPEL service dehydrates. This is also known as master detail with indexing.
An example of master detail with indexing is entity variables created on master detail records such as an order header with lines, accessing the lines individually with array subscripting.
Involved components:
SOA Composite with a BPEL process service component and a SOAP binding.
ADF Business Components, including view objects, with a published web service interface.
When a BPEL process service component needs to perform CRUD operations on back-end data stored in a database, you use BPEL entity variables. Entity variables can fetch data from an ADF Business Components view object through a web service interface, and manipulate the data using common BPEL assign and XPath constructs. These changes automatically synchronize with the ADF Business Components service when the BPEL instance dehydrates. Using entity variables provides the following:
Ease-of-use by abstracting data manipulation
Performance gains from the use of SDO change summaries
Strongly typed XML document to back XML element manipulations
The transaction locking strategy for SDO is optimistic. If the BPEL engine tries to update an SDO or entity variable and the current revision number is out of date, an exception will be thrown by the ADF Business Components service.
The sample code for this use case can be downloaded from http://soasamples.samplecode.oracle.com/.
To manipulate data, first you create an ADF Business Components entity object that accesses and updates the data. You then publish the business component as a web service. Next, you create a SOA composite application that includes a BPEL service component to which you add entity variables that can manipulate the data.
To manipulate data from a BPEL process service component:
Create ADF Business Components, including an application module, as documented in the chapter "Implementing Business Services with Application Modules" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Optionally create any SDO classes for view objects. For detailed procedures, see the chapter "Integrating Service-Enabled Application Modules" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
When modeling your view objects, it is important to determine which may need to be available for binding to SOA composite entities. It is possible to automatically enable services in top-level view objects referenced in a service interface create from an application module. However, you must create the SDO classes for individual view objects so as to configure the SDO name or namespace, or selectively service-enable child view objects.
Configure the service interface for the application module. For detailed procedures, see the chapter "Integrating Service-Enabled Application Modules" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
You can elect to include in your service interface custom methods, top-level service view instances, and any find operations based on view criteria.
At the end of this step, JDeveloper creates the WSDL files that will be used by the BPEL process service component to access any required methods or data.
Deploy the services to the Integrated Oracle WebLogic Server by right-clicking the nameServiceImpl class and selecting Run. Alternatively, define an ADF Business Components service interface profile and deploy it to the standalone Oracle WebLogic Server. For more information, see the sections "How to Test the Web Service Using Integrated Oracle WebLogic Server" and "How to Deploy Web Services to Oracle WebLogic Server" in the chapter "Integrating Service-Enabled Application Modules" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Add the WSDL file for the ADF Business Components service to the Resource Palette. If you are using the integrated server, you must first run your application. In the Resource Palette, create a new URL connection to the integrated server. The URL is:
http://localhost:7001/ApplicationName-ProjectName-context-root/AppModuleService Name
The URL for the embedded server is generated at the bottom of the WSDL file. Alternatively, you can open the file and copy the soap:address URI.
If you have deployed the Oracle ADF web application to a standalone server, then create a new Application Server connection in the Resource Palette. For more information about using the Resource Palette, see JDeveloper Online Help.
Note:
The ADF Business Components service must be running in order for it to be discoverable.Create a SOA composite application that includes a BPEL process service component. For detailed procedures see the chapter "Developing SOA Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
In the SOA composite application, create a reference binding from the BPEL process to the WSDL file for the ADF Business Components service. When creating the reference binding, be sure to select the WSDL from the Resource Palette.
Note:
The ADF Business Components service must be running in order for it to be discoverable.For more information about creating bindings, see the section "Adding Service Binding Components" in the chapter "Developing SOA Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite and "Using ADF Model in a Fusion Web Application" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
In the BPEL process service component, create an entity variable. This type of variable delegates BPEL data manipulation operations to an underlying data provider implementation, in this case the business component.
For more information about creating entity variables, see the chapter "Manipulating XML Data in a BPEL Process" of the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
When you create the entity variable, ensure that you select the business component as the Partner Link.
Add a Bind activity to the BPEL process service component. This activity establishes the key to pass to the ADF Business Components service when the SDO will be fetched from the database.
Example 35-1 shows the XML for a bind activity that establishes OrderId as the key that will be passed to retrieve orders.
Example 35-1 Bind Activity Establishes the Key
<bpelx:bindEntity name="BindEntity_1" variable="orderEntityVar">
<bpelx:key keyname="ns4:OrderId">bpws:getVariableData('inputVariable',
'payload','/client:BPELEntityVarADFBCProcessRequest/client:orderID')
</bpelx:key>
</bpelx:bindEntity>
For more information about Bind activities, see the section "Adding Service Binding Components" in the chapter "Developing SOA Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite and "Using ADF Model in a Fusion Web Application" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Add an Assign activity to the BPEL process service component that will manipulate the data.
Example 35-2 shows the XML for an assign activity that first assigns the value from the entity variable to another variable, then takes the value of the entity variable and manipulates it using an XPath expression. The change operations are mapped back to the SDO automatically. For more information about using XPath operations, see Section 35.7.2, "Support for XPath Operations."
Example 35-2 Assign Activity Manipulates an Entity Variable Value
<assign>
<copy>
<from expression="$orderEVar/fdsm:OrderTotal + 1" />
<to variable="orderEVar" query="fdsm:OrderTotal" />
</copy>
</assign>
Once the BPEL process service component hits a breakpoint activity (receive, onMessage, wait, onAlarm) the instance is dehydrated. When dehydration happens, or the scope where entity variables are declared completes, all related entity variables that have been loaded flush their changes back to the business component, and from there to the database. For more information, see Section 35.7.1, "When Entity Variables Flush Changes Back to ADF Business Components."
You can use sensor variables to monitor the service data object. For more information, see the following links:
"Using Oracle BPEL Process Manager Sensors" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
"Monitoring BPEL Process Service Components and Engines" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
"Managing SOA Composite Applications" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
Deploy the ADF Business Components web service to the Integrated Oracle WebLogic Server with SOA infrastructure. Then deploy the SOA composite application.
To secure this pattern, it is recommended that you follow the same steps as described in Section 34.5, "Securing the Design Pattern."
To properly verify this design pattern, you should test your ADF Business Components service, then deploy and test the SOA composite application.
To verify this design pattern:
Test your Oracle ADF web application using the various testing and debugging methods described in the chapter "Testing and Debugging ADF Components" of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. For information about testing the ADF Business Components service, see the chapter "Integrating Service-Enabled Application Modules" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Deploy the SOA composite application to the standalone WLS where the SOA infrastructure has been installed. Because you created a web service binding from the SOA composite application to the ADF Business Components web service, the ADF Business Components web service need not be deployed to the SOA infrastructure.
Test the deployed SOA Composite service using Fusion Middleware Control Console. Every deployed service has its own test page, so you can quickly test that the service functions as you expect. For more information, see "Managing SOA Composite Applications" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
Tip:
The use of entity variables greatly affects the ability to unit test the process in an isolated environment. Unit tests of processes that use entity variables usually require managing the backend database state.Following are tips that may help resolve common issues that arise when developing or running this use case.
To get more logging information, add logger reference oracle.soa.bpel.entity.
Before you implement these design patterns, you may want to know more about when variables flush changes back to the business component, how to test variables without invoking ADF Business Components, support for XPath operations, and how to invoke multiple services.
There are three points within the flow when an entity variable flushes its changes back to the ADF Business Components service:
When the BPEL instance dehydrates. This happens whenever a breakpoint activity is reached (for example receive, onMessage, wait, onAlarm) or execution reaches the end of the flow definition.
When the BPEL instance dehydrates as a result of reaching its activity processing threshold. By default, the threshold is set to 600 activities. The property dspMaxRequestDepth in the file bpel-config.xml sets the threshold.
When execution reaches the end of the scope, if the entity variable has been declared locally (for example within a scope). If the entity variable is declared globally, it flushes changes when the instance completes.
To illustrate, Example 35-3 includes a locally declared entity variable.
Example 35-3 Local Entity Variable
<scope name="myScope">
<variables>
<variable name="orderEVar" element="fdsm:orderInfo2SDO"
bpelx:entity.si="OrderService" />
</variables>
<bpelx:bindEntity name="BindEntity_1" variable="orderEntityVar">
<bpelx:key keyname="ns4:OrderId">bpws:getVariableData(
'inputVariable','payload','
/client:BPELEntityVarADFBCProcessRequest/client:orderID')</bpelx:key>
</bpelx:bindEntity>
<assign> ... </assign>
</scope>
Because the variable was defined locally within the scope myScope, once that scope completes, the variable declaration is no longer accessible from the outer enclosing scope. At this point, changes made to the variable from the Assign activity will be flushed to the ADF Business Components service.
Example 35-4 shows an entity variable defined globally, hence its scope will complete when the instance completes.
Example 35-4 Global Entity Variable
<process ...>
<variables>
<variable name="orderEVar" element="fdsm:orderInfo2SDO"
bpelx:entity.si="OrderService" />
</variables>
<sequence>
<receive ...>
<bpelx:bindEntity name="BindEntity_1" variable="orderEntityVar">
<bpelx:key keyname="ns4:OrderId">bpws:getVariableData(
'inputVariable','payload','
/client:BPELEntityVarADFBCProcessRequest/client:orderID')</bpelx:key>
</bpelx:bindEntity>
<assign ...>
</sequence>
</process>
XPath operations can be used in Assign activities to manipulate data. Most XPath operations are supported. Following are noted limitations:
Nested predicates, such as -nameStep1[x1[y1>3]] are not supported.
Multiple steps within a predicate, such as -nameStep1[x1/y1>3] are not supported.
There are limitations present in the ADF Business Components SDO binding layer, such as numeric computation and function. However, BPEL's XPath layer will rewrite the expression into a form supported by ADF Business Components. For example:
- nameStep1[x1 > 23 + 45 and y1 = concatenate( 'a', 'b' ) ) ]
All entity variables are stored in the BPEL dehydration store. However, BPEL only stores the key data required for the variable and not the variable in its entirety. When loading these variables upon re-hydration, BPEL runs a find request on the variable to reload the variable data. However, the Oracle ADF web application may have changed the variable, leading to potential loss of data integrity.
You can check the variable for data integrity by running bpelx:entity.doVersionCheck = "true".
doVersionCheck checks for ObjectVersionId. If this returns a different value from that in the BPEL store, a fault is raised.
Example 35-5 illustrates the verification of variable data integrity.
Example 35-5 Checking Variable Data Integrity
// Checks the variable version. <variable name="Variable_1" element="ns1:emp" bpelx:entity.si="Service1" bpelx:entity.doVersionCheck="false"/> // Enables doing a custom version check on custom fields Sal and Deptno. <variable name="Variable_1" element="ns1:emp" bpelx:entity.si="Service1" bpelx:entity.customVersionCheck="ns1:Sal ns10:Deptno "/>
Note:
The version fields must exist in the data object returned. If the Xpath query fails, an exception is thrown. Make sure the custom version fields are defined in the XSD and that the names match.The pattern described in this chapter and the pattern described in Chapter 34, "Orchestrating ADF Business Components Services" can be easily combined.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|