37 Manipulate Back-End Data from a SOA Composite

This chapter describes what updates created in a SOA composite application need to do to perform create, read, update, or delete (CRUD) operations on back-end data stored in a database.

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.

37.1 Introduction to the Recommended Design Pattern

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.

37.2 Example

The sample code for this use case can be downloaded from Oracle SOA Suite sample.

37.3 How to Manipulate Data from a BPEL Process Service Component

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.
Optionally create any SDO classes for view objects.

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.

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

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 37-1 shows the XML for a bind activity that establishes OrderId as the key that will be passed to retrieve orders.
Add an Assign activity to the BPEL process service component that will manipulate the data.

Example 37-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 Support for XPath Operations.

When 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 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:
Deploy the ADF Business Components web service to the Integrated Oracle WebLogic Server with SOA infrastructure. Then deploy the SOA composite application.

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

Example 37-2 Assign Activity Manipulates an Entity Variable Value

<assign>
    <copy>
        <from expression="$orderEVar/fdsm:OrderTotal + 1" />
        <to variable="orderEVar" query="fdsm:OrderTotal" />
    </copy>
 </assign>

37.4 Securing the Design Pattern

To secure this pattern, it is recommended that you follow the same steps as described in Securing the Design Pattern.

37.5 Verifying the Deployment

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

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.

37.6 Troubleshooting the Use Case

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.

37.7 What You May Need to Know About Manipulating Back-end Data from a SOA Composite

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.

37.7.1 When Entity Variables Flush Changes Back to ADF Business Components

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 due to 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 37-3 includes a locally declared entity variable.

Because the variable was defined locally within the scope myScope, after 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 37-4 shows an entity variable defined globally, hence its scope will complete when the instance completes.

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

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

37.7.2 Support for XPath Operations

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 37-5 illustrates the verification of variable data integrity.

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.

Example 37-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 "/>

37.7.3 Invoking an ADF Business Components Service and Entity Variables in the Same BPEL Process Service Component

The pattern described in this chapter and the pattern described in Orchestrating ADF Business Components Services can be easily combined.