9.1 Verify That All External Partners Are Available

Before you upgrade the Oracle SOA Suite application to 11g, you must ensure that the external partners (in the form remote Web services) are up and running and available.

Oracle JDeveloper 11g must be able to access these external partners, as well as the Oracle BPEL Process Manager and Oracle Enterprise Service Bus services deployed on 10g; otherwise, it can not properly migrate the projects in your application to 11g.

To verify that the required Web services are available, you should review each of the projects in your Oracle SOA Suite applications before you migrate them to 11g. For example, you can review the Oracle BPEL Process Manager configuration files for each project and verify that the Web services URIs referenced in those configuration files are valid and working.

However, there are some limitations to what the Oracle JDeveloper Migration Wizard can perform automatically. Refer to specific sections of this chapter for information about the types of manual tasks you might have to perform on your Oracle SOA Suite applications before or after using the Migration Wizard.

Applying the Latest Patch Sets

For best results, Oracle recommends that you apply the most recent patch sets to your Oracle SOA Suite environment and that you use the latest 10g Release 3 (10.1.3) Oracle JDeveloper before upgrading to 11g.

Keeping Oracle JDeveloper and Oracle SOA Suite at the Same Version Level

As a general rule, you should always update your Oracle SOA Suite and Oracle JDeveloper installations at the same time and run the same version of both these Oracle products.

Verifying That You Have the Required SOA Composite Editor Oracle JDeveloper Extension

To upgrade your Oracle SOA Suite applications to 11g, you must have the Oracle SOA Composite Editor extension for Oracle JDeveloper 11g.

To verify that the extension is installed, select About from the Oracle JDeveloper Help menu, and click the Version tab. You should see an entry in the list of components called SOA Composite Editor.

If this component does not appear on the Version tab of the About dialog box, close the About dialog and select Check for Updates from the Help menu. Use the Check for Updates wizard to locate and install the latest version of the SOA Composite Editor extension.

Table 9-1 describes the APIs you can use in an Oracle SOA Suite application. For each Oracle Application Server 10g API, it provides a summary of the changes for Oracle Fusion Middleware 11g and where you can get more information about upgrading your applications that use the API.

9.4.1.1.1 Overview of the Oracle Business Rules SDK and API Changes for 11g

In Oracle Fusion Middleware11g, the Oracle Business Rules SDK and API has been significantly improved.

In Oracle Application Server 10g, developers were required to manually manage accessing the repository and creating and using RuleSession instances. In Oracle Fusion Middleware 11g, the Decision Point API and decision function features provide an interface and implementation that simplifies the definition and execution of rules.

However, if you want to continue to use the Oracle Business Rules SDK in the same way as you did for 11g, then the following sections describe how to directly translate the Oracle Business Rules 10g SDK to the 11g SDK.

All of the classes discussed in this section are in the rulesdk2.jar file and under the oracle.rules.sdk2 package.

9.4.1.1.2 Accessing a Dictionary in the Development Environment

In Oracle Business Rules 10g, it was common for an application developer to use a file-based repository while developing the application, and then switch to using a WebDAV repository for production.

In Oracle Business Rules 11g, you can instead access the rule dictionary file directly before it is packaged into a format which can be deployed to MDS.

In the following examples, compare the code required to access a dictionary in development mode in 10g (Example 9-1) with the code required in 11g (Example 9-2).

Note that in general, you should use the Decision Point API rather than continuing to access the RuleRepository directly.

Example 9-1 Accessing a Dictionary with Oracle Business Rules 10g in a Development Environment

9.4.1.1.3 Accessing a Repository in a Production Environment

In Oracle Business Rules 10g, WebDAV was the recommended production repository.

In Oracle Business Rules 11g, WebDAV is no longer supported and Metadata Services (MDS) is the recommended repository. Also, the dictionary "name" and "version" have been replaced with a "package" and "name" (similarly to the Java class naming scheme).

In Oracle Business Rules 10g, the version did not provide true versioning. In Oracle Business Rules 11g, the equivalent to specifying a version is to simply change the name. For example, a 10g dictionary with the name foo.bar.MyDict and version 2 would in 11g be packaged as foo.bar and name MyDict2.

In the following examples, compare the code required to access a dictionary in production mode in 10g (Example 9-3) with the code required in 11g (Example 9-4).

Example 9-3 Accessing a Dictionary with Oracle Business Rules 10g in a Production Environment

9.4.1.1.5 Upgrading WebDAV Oracle Business Rules Project

If you are upgrading Oracle Business Rules 10g project that includes WebDAV, then Oracle recommends that you use Java JDK for upgrading to Oracle Business Rules 11g. If you are using Oracle JRockit as the JVM then the upgrade process will get stuck.

Oracle SOA Suite 11g introduces a new infrastructure management API that replaces several other APIs previously available in Oracle SOA Suite 10g.

For more information about the new API, refer to the Oracle Fusion Middleware Release Notes, which are available as part of the Oracle Fusion Middleware 11g documentation library.

9.4.2 Reviewing Your Projects for Dependent JAR Files

If you are upgrading an Oracle SOA Suite application that depends upon references to custom JAR file libraries. note that these references may not get upgraded automatically when you open and upgrade your application in Oracle JDeveloper 11g.

As a result, you should review your projects for these types of dependencies and, after the upgrade, make sure that you add any missing references, by selecting the Libraries and Classpath link in the Oracle JDeveloper 11g Project Properties dialog.

If you are upgrading an application that uses Web services resources outside your company firewall, you must modify a configuration file that will enable the upgrade to accesses proxy settings and adjust them accordingly during the upgrade of the application.

To configure Oracle JDeveloper 11g to use the proxies during the upgrade process:

Locate the following file in the JDEV_HOME/bin directory:

ant-sca-upgrade.xml

Edit the file and modify the following settings to identify the proxy server and port required to resolve the Web services addresses for the applications you are upgrading.

Note that there are two locations in the file to modify these settings. One location is used to set the proxy when you are upgrading an ESB project to Oracle Mediator 11g; the other is used when you are upgrading Oracle BPEL Process Manager projects.

Stop and start Oracle JDeveloper 11g so your changes can take effect and then open and upgrade your application in Oracle JDeveloper 11g.

9.4.4 Recreating build.xml and build.properties Files Not Upgraded by the Migration Wizard

When you open and upgrade an application in Oracle JDeveloper 11g, the build.xml and build.properties files associated with your application projects are not upgraded.

Instead, you must recreate these files in Oracle JDeveloper 11g after the upgrade.

9.4.5 Upgrading Projects That Use UDDI-Registered Resources

The following information is important if any of your Oracle BPEL Process Manager or Oracle Enterprise Service Bus 10g projects use remote resources that are registered in a UDDI (Universal Description, Discover and Integration) registry, such as Oracle Service Registry (OSR).

9.4.5.1 Verifying that serviceKey Endpoints Are Available Before Upgrade

If you have a 10g Release 3 (10.1.3) project that references an endpoint URL that uses a serviceKey from OSR, then you must be sure that the endpoint URL is up and available when you upgrade the application. Otherwise, the upgrade of the application will fail. To prevent such a failure, verify that the endpoint URLs are available, and if necessary, modify the endpoint URLs in bpel.xml or the routing service to point to new URL which is accessible.

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.

The Oracle SOA Suite Command-Line Upgrade Tool is compatible (with restrictions) with the Oracle JDeveloper Migration Wizard. In other words, you can choose to remain in command-line mode all the way through the upgrade process (upgrade, compile, package, and deploy), or you can choose to move to Oracle JDeveloper, or you use both tools, with no functionality loss.

However, it is important to note that the command-line tool upgrades SOA project artifacts only. Other Oracle JDeveloper artifacts (for example, the .jpr and .jws files) are ignored.

To work around this restriction, note the following:

The Oracle SOA Suite Command-Line Upgrade Tool copies files from the BPEL suitcase directory (the BPEL subdirectory or the directory hosting the BPEL files) to the specified target directory, specified on the command line.

The above copying action does not copy the .jpr or .jws files. After the upgrade, the target directory contains only the upgraded SOA project contents.

To remedy this problem in Oracle JDeveloper, you can create a new application or new project, and then define the project directory to be the newly upgraded composite directory.

If you attempt to use the Oracle SOA Suite Command-Line Upgrade Tool to upgrade an application that contains Oracle Human Workflow projects, note that the tool will create a separate project for each upgraded task form.

This resulting project is an Oracle ADF project and Oracle ADF does not support command line deployment and Oracle JDeveloper deployment. As a result, after using the Oracle SOA Suite Command-Line Upgrade Tool, you must open the upgraded projects in Oracle JDeveloper 11g deploy it from JDeveloper.

After the upgrade is complete, run the SCA-Compiler (ant-sca-compile.xml) which will verify the migrated sources.

Because the SCA-Upgrade will not generate complete artifacts in all cases, you will see some errors or warnings from SCA-Compiler with information on how to fix them. Check the SCA Compiler for reference.

After you get a clean pass from the SCA-Compiler, use the ant-sca-package.xml tool to package your application.

You can then deploy the application using ant-sca-deploy.xml. After deployment, your project will be available to the server for testing.

Note, however, that in most cases, you will likely want to open the upgraded project in Oracle JDeveloper 11g. From there, you can easily review, verify, and make any necessary updates to the application projects.

The Oracle SOA Suite Command-Line Upgrade Tool uses this value to create an application subdirectory inside the target directory. The tool then copies the upgraded project files to application subdirectory.

-Drevision

Need Info ------------

bpel_or_mediator_identifier

Can be one of two values:

bpel, to identify a Oracle BPEL Process Manager project that you want to upgrade to Oracle BPEL Process Manager 11g

mediator, to identify an Oracle Enterprise Service Bus project that you want to upgrade to Oracle Mediator 11g.

If you do not specify a value, then the command-line tool assumes you are upgrading an Oracle BPEL Process Manager project.

When you run the Oracle SOA Suite Command-Line Upgrade Tool, note the following:

If the sourceDir and the targetDir directories are the same directory, then the command-line upgrade tool will automatically create a backup of the directory before migration; if you must re-run the upgrade, you can restore the source files using the backup directory. You can identify the backup directory by the ".backup" suffix in its name.

If the sourceDir and targetDir directories are different, a backup directory is not created and is not necessary, because the files in the sourceDir are not modified during the migration.

After upgrade, the logs can be found in the following output directory:

Using the Oracle SOA Suite Command-Line Upgrade Tool, you can merge BPEL projects together and create a single composite. This is not possible when you use the Migration Wizard in Oracle JDeveloper.

To combine multiple BPEL projects into a single composite, provide multiple source directories as part of the -Dsource property on the command line.

Path separators can be a colon (:) or a semicolon (;). Ant will convert the separator to platform's local conventions. As a guideline, also use double quotes to identity the multiple source directories to prevent Ant from parsing the input in an unexpected manner.

The first source directory specified will be considered as the root of the 11g project and will determine the composite name.

The first project in the source list is considered the root project and only those services are exposed as Composite Services. Anytime you use the merge feature, it is recommended that the projects be related.

Merging of projects is supported for BPEL projects only. ESB projects cannot be merged with other BPEL or other ESB projects.

If you use domain value maps (DVMs) or Cross References in your Oracle BPEL Process Manager 10g or Oracle Enterprise Service Bus 10g projects, then note the following:

The xPath functions you use to access the domain value maps or cross references are upgraded automatically to Oracle BPEL Process Manager and Oracle Mediator 10g when you open and upgrade your applications in Oracle JDeveloper 11g.

However, you must perform a manual upgrade task to upgrade the domain value maps and cross references that are saved in the Oracle Enterprise Service Bus repository. The upgrade process moves the domain value maps from the ESB repository to the Oracle Fusion Middleware 11g Metadata Services (MDS) repository.

In the Create SOA Project from SOA Archive Dialog Box, select JAR Options in the navigation tree on the left, and then click Browse to locate the sca_XrefDvmFiles10g_rev1.0.jar file that you created previously in this procedure.

Select File Groups > Project Output from the navigational tree on the left, and enter XrefDvmFiles10g in the Target Directory in Archive field.

Click OK to create the new SOA project, which is called XrefDvmFiles10g.

The new project consists of an empty composite, along with the upgraded XRef and DVM files.

Create a JAR file for the XRef and DVM metadata, and then deploy the JAR file to the Oracle SOA Infrastructure.

After you upgrade the DVM and cross reference metadata to 11g, you can then use Oracle JDeveloper 11g to modify the entries in the XrefDvmFiles10g project as needed. Each time you make changes, you must then transfer them to the proper MDS repository using the same deployment process.

If you have Oracle SOA Suite 11g cross reference (XREF) runtime data in an Oracle database and you want to use it with Oracle SOA Suite 11g, then you can use the following procedure to upgrade it for use with Oracle SOA Suite 11g.

This procedure and utility are necessary because the XREF database schema table (XREF_DATA) has changed for Oracle Fusion Middleware 11g. Perform the steps described in this section to modify the 10g XREF data so it adheres to the 11g schema format.

Note that this procedure assumes your 10g XREF data is in one Oracle database and your new Oracle Fusion Middleware 11g data is in another Oracle database. This scenario is known as an "out-of-place" data upgrade.

Log in with SYS user privileges to the Oracle database where your Oracle SOA Suite 11g XREF runtime data is stored, and create a database link for accessing the second database where your XREF 10g data is stored.

In the previous example, replace the values shown in italics with the information required to connect to the database where your XREF data is stored.

Change directory to following subdirectory, which was created inside the local folder where you unzipped the XREF 10g to 11g Data Upgrade Utility:

XREF10gto11gDataUpgradeUtility/scripts

Use a text editor to open the following SQL file:

Upgrade10gXrefTo11gXref.sql

Make the following edits to contents the file:

Locate the following entry in the Upgrade10gXrefTo11gXref.sql file and change the [TO BE FILLED] string in the file to an oramds: URL that points to the shared MDS data location:

--specify the MDS_FOLDER_LOCATION where the shared xref artifacts should reside, -- 10g table name will get prefixed by this location. -- MDS_FOLDER_LOCATION varchar2(1000) := 'oramds:/abc/ABCMetaData/xref/'; MDS_FOLDER_LOCATION varchar2(1000) := '[TO BE FILLED]';

For more information about the oramds: URL protocol, see "How to Deploy Shared Metadata" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Optionally, change the default value of the commitperbatch parameter (the default is 2000).

This parameter specifies the number of records which should be committed per batch during migration.

From the same directory, log in to Oracle database that hosts the Oracle SOA 11g XREF data as the XREF user, and enter the following:

set serverout on;
@Upgrade10gXrefTo11gXref.sql

These commands upgrade the data and show you the progress of the upgrade as server output log.

In cases where the 10g XREF data does not conform to the 11g schema, or if any errors or exceptions occur during the upgrade process, the utility copies any corrupted records to the XREF_DATA_CORRUPTED table. This table has all the columns of XREF_DATA, with an additional column called EXCEPTION_CAUSE. This column stores the reason for the exception with the row number.

When you are finished upgrading the XREF data, remove the database link using the following SQL command as the SYS user:

DROP PUBLIC DATABASE LINK dblink10g;

If any records are not migrated successfully, the temporary tables XREF_DATA_CORRUPTED and TEMP_UPGRADE_XREF_LOG are not removed by the utility and must be cleaned up manually.

Scripting on this page enhances content navigation, but does not change the content in any way.