This chapter provides important supplementary information upgrading Oracle BPEL Process Manager applications to Oracle Fusion Middleware 11g.
Use Chapter 8, "Overview of Upgrading Oracle SOA Suite, WebCenter, and ADF Applications" for the tasks required to upgrade any Oracle SOA Suite, WebCenter, and ADF application.
Use the following sections to learn about the upgrade tasks you will likely need to perform to upgrade your Oracle BPEL Process Manager applications and projects to Oracle Fusion Middleware 11g:
Manual Upgrade Steps After Migrating Oracle BPEL Process Manager Applications
Additional Considerations for Oracle BPEL Process Manager Applications
The following sections describe some of the common upgrade tasks you will have to perform after you open your Oracle Application Server 10g Oracle SOA Suite application in Oracle JDeveloper 11g.
These tasks represent items that are not upgraded automatically by the Oracle JDeveloper Migration Wizard:
Providing Missing Binding Information for External References
Correcting Problems With Oracle BPEL Process Manager Test Suites
Using Oracle BPEL Process Manager Deployment Plans After Upgrade
Upgrading Fault Policies in an Oracle BPEL Process Manager Project
Post-Upgrade Steps for Projects That Use WSIF Bindings to EJBs
This section describes how to fix compiler warning messages about missing bindings after you upgrade an Oracle BPEL Process Manager project in Oracle JDeveloper.
Why the Warning Messages Occur When a source project in your application depends on Oracle Application Server 10g Release 3 (10.1.3) Oracle BPEL Process Manager or Oracle Enterprise Service Bus (ESB) services, then as a pre-cursor to migration, the Oracle JDeveloper Migration Wizard creates local copies of their abstract WSDLs.
The abstract WSDLs, by definition, lack service and port endpoint information. During upgrade, when the Migration Wizard creates external composite references for the service dependencies, the references are created as abstract references with no binding information.
These abstract references are flagged with WARNING messages in the upgrade log. After upgrade, when you attempt to compile the projects, Oracle JDeveloper will generate compilation errors alerting you to the presence of abstract references in the composite.
Using 10g Release 3 (10.1.3) or 11g Dependency Services Based on the upgrade and deployment schedules of all the services in the dependency tree, you can choose to continue to use 10g Release 3 (10.1.3) dependency services or proceed with the upgrade and redeployment of the dependency service.
In general, Oracle recommends that users study their source project and their dependencies before any upgrade work. This analysis will result in a smoother upgrade experience.
How to Correct Binding Errors Discovered During the Recompile To correct binding errors due to the abstract references, right-click on the reference node in the Oracle JDeveloper 11g composite editor and choose the correct concrete WSDL. If you want to continue using a 10g Release 3 (10.1.3) dependency service, you can do so. Some of the dependency service endpoint URLs that are captured in the upgrade log can be used for this step.
You can also redesign the dependency in Oracle JDeveloper 11g, using the WSIL Browser (Resource Palette), and discover the service from the UI in the composite modeler.
For more information, refer to the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
During upgrade in Oracle JDeveloper, BPEL test suites are converted to composite test suites. However, only the "instance initiate" action is migrated. This results in a composite test which initiates only a test run. The rest of any BPEL-based test actions are not automatically migrated and must be manually set up after the upgrade.
To set up the tests in your 11g environment, refer to "Testing SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Deployment and configuration plans that you set up in Oracle Application Server 10g for your Oracle BPEL Process Manager user projects are not upgraded in Oracle JDeveloper 11g.
In Oracle Fusion Middleware11g, a composite can be accompanied by deployment and configuration plan during deployment. However, you must create the 11g deployment plan manually, after you have migrated the application in Oracle JDeveloper.
For more information about creating configuration plans in 11g, see "Moving SOA Composite Applications to and from Development, Test, and Production Environments" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
When you open your 10g application in Oracle JDeveloper and use the Oracle JDeveloper Migration Wizard to upgrade the application, any fault policies and bindings that you set up in a user project are not automatically upgraded to 11g.
The reasons are as follows:
In Oracle BPEL Process Manager 10g, fault policies were stored with the server and bindings were either stored with the server or specified in bpel.xml. In Oracle BPEL Process Manager 11g, fault policies and fault bindings are stored in the Oracle JDeveloper 11g project.
In general, fault policies and bindings in Oracle BPEL Process Manager 11g are different than those in previous releases. For example, the file name and syntax is different, fault policies apply both to Oracle Mediator and Oracle BPEL Process Manager, and bindings are at a reference, component, and composite level in 11g.
For these reasons, you must manually recreate the fault policies and bindings in the Oracle JDeveloper 11g project after you upgrade your applications.
Similarly, when you upgrade an Oracle Enterprise Service Bus 10g Release 3 (10.1.3) project to 11g, you must add the retry parameters defined in esb_config.ini file to the 11g fault-policy.xml file.
For more information, see:
"Using Fault Handling in a BPEL Process" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
"Using Mediator Error Handling" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
If the 10g Release 3 (10.1.3) application you are upgrading includes a project where all the project artifacts are in one folder and the BPEL artifacts are not separated into their own folder in the project, then the Oracle JDeveloper Migration Wizard will not be able to upgrade those artifacts.
To avoid this problem, do one of the following:
Before upgrading the project, use Oracle JDeveloper 10g to create a BPEL folder and move all the artifacts (except the build.xml and build.properties files) into that folder. Then you can proceed with upgrading the project.
Use the Oracle SOA Suite command-line upgrade tool. The command-line tool will upgrade the artifacts even if a BPEL folder does not exist in the project. For more information, see Section 9.3.7, "Using the Oracle SOA Suite Command-Line Upgrade Tool".
When you have Oracle SOA Suite 10g projects that use WSIF bindings to communicate with Enterprise Java Beans (EJBs), then you must make some modifications to those projects after they are upgraded to 11g.
For example, after you upgrade a project that uses WSIF bindings and EJBs, it will fail to run on due to WSIF binding errors.
To work around the these problems, you typically must perform the following steps after you have upgraded the project to Oracle JDeveloper 11g:
Replace the properties of the <binding.wsif> entry in the composite.xml file with the correct JNDI related properties for Oracle WebLogic Server.
For example, the following are typical properties set for a Oracle WebLogic Server domain for an application called the BankTransferDemo application, which was deployed previously on Oracle Application Server 10g Release 3 (10.1.3):
<binding.wsif
port="......."
location="......">
.
<property name="jndiName">
ejb/session/BankTransfer
</property>
.
<property name="java.naming.factory.initial">
weblogic.jndi.WLInitialContextFactory
</property>
.
<property name="java.naming.provider.url">
t3://[SERVER HOST NAME]:[SERVER PORT]
</property>
.
<property name="java.naming.security.principal">
[DOMAIN ADMIN USER NAME]
</property>
.
<property name="java.naming.security.credentials">
[DOMAIN ADMIN PASSWORD]
</property>
.
</binding.wsif>
Copy the EJB classes to the following directory in your newly upgraded 11g project:
SOA_JDEV_PROJECT_HOME/SCA-INF/classes/
For more information about using Oracle JDeveloper to modify your Oracle SOA Suite applications, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
The following sections describe additional considerations you should review after upgrading Oracle BPEL Process Manager applications:
Section 10.2.1, "Verifying New and Deprecated Properties in the bpel.xml Deployment Descriptor"
Section 10.2.3, "Change in Support for Multiple BPEL Implementations"
Section 10.2.5, "Upgrading Projects With the transaction=participate Property"
Section 10.2.6, "Specifying Domain Descriptor Properties in Oracle BPEL Process Manager 11g"
Section 10.2.7, "Upgrading Applications That Use Multiple Oracle BPEL Process Manager Domains"
Section 10.2.8, "Verifying Process ID, Project Name, and BPEL File Name Conventions Before Upgrade"
Section 10.2.9, "Verifying Oracle BPEL Process Manager 11g Namespace Prefixes in XPath Functions"
If any of your Oracle Application Server 10g Release 3 (10.1.3) applications reference any properties that were stored in the bpel.xml deployment descriptor, note that these properties are now set in the composite.xml deployment descriptor file.
For more information about the properties available in the composite.xml deployment descriptor, as well as important information about properties that are no longer supported in Oracle Fusion Middleware 11g, refer to "Deployment Descriptor Properties" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
When you open and upgrade your applications in Oracle JDeveloper 11g, any custom XPath functions in the application projects are not upgraded automatically.
As a result, after you upgrade your application, you must copy any XPath function classes into the server classpath and register the function in the server configuration file. This is a manual step because the Oracle JDeveloper Migration Wizard cannot assume the server information.
For more information, refer to "Creating User-Defined XPath Extension Functions" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
You cannot upgrade a single BPEL file with multiple implementations in Oracle BPEL Process Manager 11g.
To migrate and merge multiple 10g Release 3 (10.1.3) projects with a single BPEL implementation file, you must rename the BPEL file in each project. In the bpel.xml file in each project, the bpel filename and deployment ID name must be renamed the same name, as well.
Before you upgrade the application, review the bpel.xml file and *.bpel file. Make sure that the BPEL file name and the process name are the same; then review the bpel.xml file and verify that the BPEL file name is the same as the deployment ID name.
If you created an Oracle BPEL Process Manager 10g project that used correlation sets in an asynchronous service, as described in the Oracle BPEL Process Manager 10g Release 3 (10.1.3) Developer's Guide, make sure that the correlation set properties file uses the following proper naming convention:
BPEL_FILE_NAME_Properties.wsdl
If this file naming convention is not followed in the Oracle BPEL Process Manager 10g project, the properties will not be upgraded correctly. If you need to change the name to meet the file naming conventions, then also update the wsdl file that imports the property file name, accordingly.
If you open and upgrade an Oracle BPEL Process Manager 10g project that has a configuration property, transaction=participate, then that property will not be migrated to 11g when you open the application in Oracle JDeveloper 11g. This configuration property is no longer supported in Oracle Fusion Middleware 11g.
If you open and upgrade an Oracle BPEL Process Manager 10g project has a partnerLink binding property, transaction=participate, then that property will be dropped on the caller side. The callee project instead should have the property setting bpel.config.transaction=required. This caller to callee setting propagation is not performed by upgrade and must be performed manually after you upgrade the application and before you attempt to deploy it on Oracle Fusion Middleware 11g.
In Oracle BPEL Process Manager 10g, you specify domain properties in the domain.xml descriptor file.
In Oracle BPEL Process Manager 11g, you specify Oracle BPEL Process Manager engine properties in bpel-config.xml and soa-infra-config.xml (both are accessible as MBeans).
Table 10-1 compares the domain descriptor properties available in Oracle BPEL Process Manager 10g and Oracle BPEL Process Manager 10g.
There is only one domain in Oracle BPEL Process Manager 11g, which means that these properties will affect the entire server.
Table 10-1 Domain Descriptor Properties in Oracle BPEL Process Manager 10g and 11g
| Oracle BPEL Process Manager 10g in domain.xml file | Oracle BPEL Process Manager 11g MBean Property | Description |
|---|---|---|
|
auditDetailThreshold |
auditDetailThreshold |
The maximum size (in bytes) of an audit trail details string before it is stored separately from the audit trail. If a details string is larger than this threshold, then it will not be immediately loaded when the audit trail is initially retrieved; a link will be displayed with the size of the details string. Typically, the details string will contain the contents of a BPEL variable. In cases where the variable is very large, performance may be severely impacted by logging it to the audit trail. The 10g default value is 50 kilobytes. |
|
auditLevel |
auditLevel |
Controls the amount of audit events logged by a process. The supported logging levels are:
|
|
bpelcClasspath |
bpelcClasspath |
Server-side BPEL process compiler classpath. Any user-specific classes or libraries used by a BPEL java exec node (that have not been packaged in the BPEL archive) need to be specified here so that the server-side BPEL process compiler can successfully compile the BPEL process. |
|
datasourceJndi |
datasourceJndi (Moved to soa-infra-config.xml) |
The JNDI name for the domain data source. This data source may refer to any data source (JTA not required). |
|
deliveryPersistPolicy |
deliveryPersistPolicy |
Changes whether the delivery messages are persisted. Delivery messages include invoke message, callback message and subscription message.
|
|
dspEngineThreads |
dspEngineThreads |
The total number of threads that will be allocated to process engine dispatcher messages. Engine dispatch messages are generated whenever an activity must be processed asynchronously by the BPEL engine. If the majority of processed deployed on the BPEL server are durable with a large number of dehydration points (mid-process receive, onMessage, onAlarm, wait), greater performance may be achieved by increasing the number of engine threads. Note that higher threads counts may cause greater CPU utilization due to higher context switching costs. The 10g default value is 30 threads. Any value less than 1 thread will be changed to the default. |
|
dspInvokeAllocFactor |
N/A |
The percentage of active threads that should be tasked to process incoming invocation messages. After a thread has finished processing a message it may be retasked to process an engine or invocation message, depending upon the current thread allocation situation. This property was replaced by |
|
dspInvokeThreads |
dspInvokeThreads |
The total number of threads that will be allocated to process engine dispatcher messages. Engine dispatch messages are generated whenever an activity must be processed asynchronously by the BPEL engine. If the majority of processed deployed on the BPEL server are durable with a large number of dehydration points (mid-process receive, onMessage, onAlarm, wait), greater performance may be achieved by increasing the number of engine threads. Note that higher threads counts may cause greater cpu utilization due to higher context switching costs. The 10g default value is 30 threads. Any value less than 1 thread will be changed to the default. |
|
dspMaxThreads |
N/A |
The maximum number of active threads that will be processing messages during peak load times. This is the simplest way to throttle the performance of the domain. The maximum value is dependent upon the application server or OS configuration. This property was replaced by dsp(Engine|Invoke|System)Threads in 10.1.3.4.0. The 10.1.3.1.0 default value is 100 threads. |
|
dspMinThreads |
N/A |
The minimum number of active threads that will be processing messages during peak load times. If the current number of active threads is under this number the load factor is not taken into consideration when determining if a new thread should be allocated or not. This property was replaced by |
|
dspSystemThreads |
dspSystemThreads |
The total number of threads that will be allocated to process system dispatcher messages. System dispatch messages are general housecleaning tasks that are typically processed quickly by the server (for example, releasing stateful message beans back to the pool). Typically, only a small number of threads are required to handle the number of system dispatch messages generated during runtime. The 10g default value is 2 threads. Any value less than 1 thread will be changed to the default. |
|
expirationMaxRetry |
expirationMaxRetry |
The maximum number of times a failed expiration call (wait/onAlarm) will be retried before failing. If the activity or instance the expiration call is targeting cannot be found, the call will be rescheduled again. The 10g default is 5. |
|
expirationRetryDelay |
expirationRetryDelay |
The amount of time in seconds to wait before rescheduling a failed expiration call. The 10g default value is 120 seconds. |
|
instanceKeyBlockSize |
instanceKeyBlockSize |
The size of the block of instance ids to allocate from the dehydration store during each fetch. Instance ids for instantiated instances are pre-allocated from the dehydration store and kept in-memory. Once all of the in-memory instance ids have been exhausted, the next request will retrieve the next block from the dehydration store. Generally, the higher the block size, the less impact fetching instance ids will have on the overall performance of the engine (as the cost of allocating the block is amortized over a larger number of instances). The only downside to a large block size is the gap between instances in a clustered installation (as each node will have its own in-memory block of instance ids) and wasting instance ids if the engine is shutdown and the block is not utilized fully. The 10g default value is 10000. |
|
largeDocumentThreshold |
largeDocumentThreshold |
The maximum size (in bytes) a BPEL variable can be before it is stored in a separate location from the rest of the instance scope data. Large XML documents will severely impact the performance of the entire BPEL server if they are constantly read-in and written-out whenever processing on an instance must be performed. By writing the variable to separate storage the performance impact is limited to times when the variable is explicitly used in a BPEL activity. The 10g default value is 50 kilobytes. |
|
minBPELWait |
minBPELWait |
The minimum amount of time allowed for a BPEL wait duration. Wait times shorter than this duration will not be respected and will essentially be "skipped" altogether. The 10g default value is 2 seconds. |
|
processCheckSecs |
N/A |
The number of seconds to wait since the last time the process container checked the bpel archive before checking it again. By "checking" we mean checking the last modified time stamp on the bpel archive for a particular process; if the specified number of seconds has passed and the bpel archive file has been modified since the last time we checked, the process will be refreshed from the new archive. If not enough time has passed since the last time the stale check was performed, the currently loaded process classes will be used. To disable process checking use a value of -1; in this case once a process has been loaded the container will never check if a newer version of the same process has been deployed. The 10g default value is 1 second. This property is not relevant in 11g anymore as the SOA infrastructure now handles deployment via HTTP only. |
|
statsLastN |
statsLastN |
The size of the "most recently processed" request list. After each request is finished, statistics for the request are kept in a list. A value less than or equal to 0 will disable statistics gathering. NOTE: engine throughput may be affected slightly if this option is enabled. Please choose a reasonable value for n (1000 is the recommended value). |
|
syncMaxWaitTime |
syncMaxWaitTime |
The maximum time the process result receiver will wait for a result before returning. Results from asynchronous BPEL processes are retrieved synchronously via a receiver that will wait for a result from the container. The 10g default value is 45 seconds. |
|
txDatasourceJndi |
txDatasourceJndi (moved to soa-infra-config.xml) |
The JNDI name for the domain transactional data source. This data source must be configured for JTA support. |
|
uddiLocation |
oracle.soa.uddi.registry.inquiryUrl (moved to soa-infra-config.xml) |
The inquiry URL of the Uddi v3 compliant registry |
|
uddiPassword |
oracle.soa.uddi.registry.password (moved to soa-infra-config.xml) |
Set if UDDI is secured, password |
|
uddiUsername |
oracle.soa.uddi.registry.username (moved to soa-infra-config.xml) |
Set if UDDI is secured, username |
|
validateXML |
validateXML |
If set to "true" the engine will apply schema validation for incoming and outgoing XML documents. The 10g default value "false". |
If you have developed and deployed your Oracle Application Server 10g BPEL projects using multiple Oracle BPEL Process Manager domains, then you should be aware that Oracle Fusion Middleware 11g does not support multiple BPEL domains.
If you are using multiple domains in Oracle Application Server 10g, then you have two options when you upgrade to Oracle Fusion Middleware 11g:
You can install and configure multiple Oracle SOA Suite Oracle WebLogic Server domains. You can then map each of your Oracle BPEL Process Manager 10g domains to a separate Oracle WebLogic Server domain.
You can deploy all your Oracle BPEL Process Manager projects to a single Oracle SOA Suite Oracle WebLogic Server domain.
For more information, refer to the Oracle Fusion Middleware Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
Before you upgrade your BPEL projects to Oracle SOA Suite 11g, verify that the process ID in the bpel.xml file, the name of the BPEL project, and the name of the BPEL file are all the same value. Otherwise, you might encounter errors during the upgrade of your project in Oracle JDeveloper 11g or some elements of your project may not upgrade correctly.
In some cases, XPath function namespace prefixes used in Oracle SOA Suite 10g have changed in Oracle SOA Suite 11g. As a result, if you are using an XPath function in an upgraded application, you might encounter "function not found" errors.
For example, if your Oracle BPEL Process Manager application used the ora:parseXML() function in 10g, you might encounter the following error:
"Function of name: ora:parseXML not found. please check the spelling and try gain"
In this example, the namespace prefix for the parseXML function has changed to oraext:parseXML in Oracle SOA Suite 11g.
For more information, see "parseXML" in the "XPath Extension Functions" appendix of the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
In Oracle SOA Suite 10g, Oracle BPEL Process Manager projects could contain multiple tasks that invoke the same partner link.
Example 10-1 shows an example of a 10g composite application that defines two tasks that invoke the same partner link. If you attempt to upgrade such an application to 11g, Oracle JDeveloper generates errors when you attempt to compile the project.
To address the problem, you must modify the project before or after you upgrade the application in Oracle JDeveloper 11g so that each task invokes a unique partner link.
For more information, see "Creating a Partner Link" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Example 10-1 Oracle BPEL Process Manager 10g Project with Multiple Tasks That Use the Same Partner Link
<partnerLink myRole="TaskServiceCallbackListener" name="TaskService"
partnerRole="TaskService"
.
.
.
<invoke name="initiateTask_MainTask_1" partnerLink="TaskService"
portType="taskservice:TaskService"
operation="initiateTask"
inputVariable="initiateTaskInput"
outputVariable="initiateTaskResponseMessage">
<correlations>
<correlation initiate="yes" set="WorkflowTaskIdCor"
pattern="in"/>
</correlations>
</invoke>
.
.
.
<invoke name="initiateTask_SubTask_1"
partnerLink="TaskService"
portType="taskservice:TaskService"
operation="initiateTask"
inputVariable="initiateTaskInput"
outputVariable="initiateTaskResponseMessage">
.
.
.
</invoke>