Skip Headers
Oracle® Fusion Middleware Upgrade Guide for Oracle SOA Suite, WebCenter Portal, and ADF
11g Release 1 (11.1.1.6.0)

Part Number E10127-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Considerations When Upgrading All Oracle SOA Applications

This chapter provides important supplementary information upgrading Oracle SOA 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 understand tasks specific to upgrading Oracle SOA applications:

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.

9.2 About Using the Oracle JDeveloper 11g Migration Wizard for Oracle SOA Suite Applications

When you open an Oracle Application Server 10g Oracle SOA Suite application in Oracle JDeveloper 11g, the Oracle JDeveloper Migration Wizard attempts to upgrade your application automatically to Oracle Fusion Middleware 11g.

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.

9.3 Upgrade Tasks Associated with All Java Applications

Before you begin upgrading your Oracle SOA Suite applications, be sure to review the Oracle Fusion Middleware Upgrade Guide for Java EE, which contains information about upgrading standard Java EE applications to Oracle WebLogic Server.

If your applications contain any custom Java code, you should review the Java code against the procedures and recommendations available in the Oracle Fusion Middleware Upgrade Guide for Java EE.

9.4 Upgrade Tasks Associated with All Oracle SOA Suite Applications

The following information should reviewed when you are upgrading any Oracle SOA Suite application to Oracle Fusion Middleware 11g:

9.4.1 Understanding Oracle SOA Suite API Changes for Oracle Fusion Middleware 11g

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.

Table 9-1 Summary of Oracle SOA Suite API Changes for Oracle Fusion Middleware 11g

10g API Action for 11g 11g JavaDoc

Oracle Application Server Integration B2B Callouts Java API

Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g.

Oracle Fusion Middleware B2B Callout Java API Reference

Oracle BPEL Process Manager Workflow Services API

Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g.

Oracle Fusion Middleware Workflow Services Java API Reference for Oracle SOA Suite

Oracle Business Rules Java API

See Section 9.4.1.1, "Upgrading to the Oracle Fusion Middleware Java API for Oracle Business Rules"

Oracle Fusion Middleware Java API Reference for Oracle Business Rules

Oracle BPEL Process Manager Client Java API

See Section 9.4.1.2, "Upgrading to the Oracle Fusion Middleware Infrastructure Management Java API for Oracle SOA Suite"

See Section 9.4.1.2, "Upgrading to the Oracle Fusion Middleware Infrastructure Management Java API for Oracle SOA Suite"

Oracle BPEL Process Manager Sensor API

Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g and part of the new Infrastructure Management Java API.

"Using Oracle BPEL Process Manager Sensors" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite


9.4.1.1 Upgrading to the Oracle Fusion Middleware Java API for Oracle Business Rules

The following sections introduce the Oracle Business Rules 11g SDK and API and provide instructions for upgrading to the Oracle Business Rules 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.

When upgrading to Oracle Business Rules 11g, look first at how you can use these new features, as documented in the Oracle Fusion Middleware User's Guide for Oracle Business 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

String path; // the path to the file repository
Locale locale; // the desired Locale
// The following code assumes that the path and locale have been set appropriately
RepositoryType rt =
RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.jar");
RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt);
RepositoryContext rc = new RepositoryContext();
rc.setLocale(locale);
rc.setProperty("oracle.rules.sdk.store.jar.path", path);
repos.init(rc);

Example 9-2 Accessing a Dictionary with Oracle Business Rules 11g in a Development Environment

protected static final String DICT_LOCATION ="C:\\scratch\\CarRental.rules";
...
RuleDictionary dict = null;
Reader reader = null;
try {
  reader = new FileReader(new File(DICT_LOCATION));
  dict = RuleDictionary.readDictionary(reader, new
                   DecisionPointDictionaryFinder(null));
  List<SDKWarning> warnings = new ArrayList<SDKWarning>();
  dict.update(warnings);
  if (warnings.size() > 0 ) {
     System.err.println("Validation warnings: " + warnings);
     }
     } catch (SDKException e){
         System.err.println(e);
     } catch (FileNotFoundException e){
         System.err.println(e);
     } catch (IOException e){
         System.err.println(e);
     } finally {
         if (reader != null) { 
              try { reader.close(); } catch (IOException ioe)
                  {ioe.printStackTrace();}
     }
}
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

String url; // the URL for the WebDAV repository
Locale locale; // the desired Locale
// The following code assumes that the url and locale have been set appropriately
RepositoryType rt =
   RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.webdav");
RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt);
RepositoryContext rc = new RepositoryContext();
rc.setLocale(locale);
rc.setProperty("oracle.rules.sdk.store.webdav.url", url);
repos.init(rc);
RuleDictionary dictionaryWithInitialVersion =
                repos.loadDictionary(dictionaryName);
RuleDictionary dictionarySpecificVersion = repos.loadDictionary(dictionaryName,
                dictionaryVersion);

Example 9-4 Accessing a Dictionary with Oracle Business Rules 11g in a Production Environment

import static
    oracle.rules.sdk2.repository.RepositoryManager.createRuleRepositoryInstance;
import static
    oracle.rules.sdk2.repository.RepositoryManager.getRegisteredRepositoryType;
import static oracle.rules.sdk2.store.mds.Keys.CONNECTION;
...
private static final String DICT_PKG = "oracle.middleware.rules.demo";
private static final String DICT_NAME = "CarRental";
private static final DictionaryFQN DICT_FQN =
new DictionaryFQN(DICT_PKG, DICT_NAME);
...
RuleRepository repo =
     createRuleRepositoryInstance(getRegisteredRepositoryType(CONNECTION));
repo.init(new RepositoryContext() {{
     setDictionaryFinder(new DecisionPointDictionaryFinder(null));
}});
RuleDictionary dict = repo.load(DICT_FQN);
9.4.1.1.4 Generating RL Code

The following example shows the code required generate RL code in Oracle Business Rules 10g. In 11g, this code remains the same.

//init a rule session
String rsname = "vehicleRent";
String dmrl = dict.dataModelRL();
String rsrl = dict.ruleSetRL( rsname );
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.

9.4.1.2 Upgrading to the Oracle Fusion Middleware Infrastructure Management Java API for Oracle SOA Suite

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.

9.4.3 Upgrading Applications That Require Proxy Settings for Web Services

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:

  1. Locate the following file in the JDEV_HOME/bin directory:

    ant-sca-upgrade.xml
    
  2. 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.

    <jvmarg value="-Dhttp.proxySet=true"/>
    <jvmarg value="-Dhttp.proxyHost=PROXY_SERVER"/>
    <jvmarg value="-Dhttp.proxyPort=PROXY_PORT"/>
    

    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.

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

Refer to the following for more information:

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.

9.4.5.2 Changing to the orauddi Protocol

In Oracle Application Server 10g Release 3 (10.1.3), Oracle BPEL Process Manager and Oracle Enterprise Service Bus projects used the uddi protocol to obtain resource references from OSR. In Oracle Fusion Middleware 11g, Oracle BPEL Process Manager and Oracle Mediator projects use the orauddi protocol.

As a result, prior to upgrading your Oracle BPEL Process Manager or Oracle Enterprise Service Bus projects, you must do the following:

  1. Use the service registry to modify the registered service so it uses the new bindings supported by Oracle Fusion Middleware 11g.

    For example, in OSR, do the following:

    1. Log in to your Oracle Service Registry.

    2. On the Search tab, click Businesses.

    3. Click Add Name to search for a business by name.

    4. From the search results, click the name of the business you want to modify.

    5. In the left pane of the View Business page, right-click the service you want to modify and select Add Binding from the context menu.

    6. From the Type drop-down menu on the Add Binding page, select wsdlDeployment.In the Access Point field, enter the URL.

      For example:

      http://machine:port/Proj_ep?WSDL/
      
    7. Click Add Binding.

    8. Click Save Changes.

  2. Open and upgrade the application in Oracle JDeveloper 11g.

  3. In Oracle JDeveloper, edit the composite.xml file for the upgraded project and configure the endpoint URL using the UDDI Registry option on the Resource Palette.

For more information about the UDDI registry, visit the following URL:

http://www.oracle.com/technology/tech/soa/uddi/index.html

9.4.6 Upgrading User-Defined (Custom) XPath Functions in 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.

9.4.7 Understanding File Naming Conventions in Oracle SOA Suite 11g

Note that before you upgrade a SOA composite application, verify that the name of the application or project does not start with a number.

For example, if you attempt to upgrade a 10g sample application called 110.JMStoJMSHeaders, Oracle JDeveloper displays a "grammar validation error" when you attempt to open the composite.xml.

To work around this problem, simply rename the application and remove the number before you upgrade the application.

9.4.8 Using the Oracle SOA Suite Command-Line Upgrade Tool

The following sections describe how to use the Oracle SOA Suite command-line upgrade tool:

9.4.8.1 Benefits of Using the Oracle SOA Suite Command-Line Upgrade Tool

The Oracle SOA Suite Command-Line Upgrade Tool has the following benefits:

  • You can use the command-line tool to automate your application upgrade work, using scripts or other command-line automation tools.

  • The command-line tool upgrades both Oracle BPEL Process Manager projects, and upgrades Oracle Enterprise Service Bus 10g projects to Oracle Mediator 11g.

  • With the command-line tool, you can merge BPEL projects together and create a single composite out of multiple BPEL projects. This is not possible when you use the Oracle JDeveloper Migration Wizard.

  • The functionality is exactly the same as the JDeveloper mode when it comes to dealing with SOA project contents because the same codebase is used.

9.4.8.2 Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g

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.

9.4.8.3 Limitations When Upgrading Human Workflow Applications with the Oracle SOA Suite Command-Line Upgrade Tool

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.

For information about how to open the upgraded project in Oracle JDeveloper, see Chapter 9, "Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g".

9.4.8.4 Upgrading BPEL or ESB Projects with the Oracle SOA Suite Command-Line Upgrade Tool

The files required to run the Oracle SOA Suite Command-Line Upgrade Tool are installed automatically when you install Oracle JDeveloper 11g and when you install Oracle SOA Suite 11g:

  • When you install the Oracle SOA Suite 11g, the required XML files are installed in the bin directory of the Oracle SOA Suite Oracle home.

  • When you install Oracle JDeveloper 11g, the required XML files are installed in the bin directory of the Oracle JDeveloper home.

You can use this files in this directory, together with Apache Ant, to migrate your 10g Release 3 (10.1.3) SOA projects to 11g.

Note:

For the purposes of this procedure, it is assumed you are running the Oracle SOA Suite Command-Line Upgrade Tool from the Oracle home of an Oracle SOA Suite installation.

If you are running it from a Oracle JDeveloper home, replace ORACLE_HOME with JDEV_HOME in the following procedures.

To use the ANT project:

  1. Set the ORACLE_HOME environment variable so it is defined as the path to the Oracle SOA Suite Oracle home.

  2. Set the other environment variables that are required by the command-line tool, by running the following script:

    On UNIX systems:

    . ORACLE_HOME/bin/soaversion.sh
    

    On Windows systems:

    ORACLE_HOME\bin\soaversion.cmd
    
  3. Run the Ant project, as follows:

    ant -f ORACLE_HOME/bin/ant-sca-upgrade.xml 
           -Dsource sourceDir 
           -Dtarget targetDir 
           -DappName app_name
           -Drevision 1.0
           bpel_or_mediator_identifier
           
    

    For examples of using the Oracle SOA Suite Command-Line Upgrade Tool, see Example 9-5 and Example 9-6.

    For a description of each command-line argument, see Table 9-2.

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

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

    For more information, see Section 9.4.8.2, "Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g".

Example 9-5 Command-Line Example on the UNIX Operating System

ant -f /Disk03/Oracle/Middleware/SOA_home/bin/ant-sca-upgrade.xml
       -Dsource /disk03/myProjects/my_bpel_app/
       -Dtarget /disk03/my11gProjects/my_bpel_app/
       -Drevision 1.0
       -DappName my_bpel_app
       bpel

Example 9-6 Command-Line Example on the Windows Operating System

ant -f C:\Oracle\Middleware\SOA_home\bin\ant-sca-upgrade.xml
       -Dsource C:\myProjects/my_bpel_app/
       -Dtarget C:\my11gProjects/my_bpel_app/
       -Drevision 1.0
       -DappName my_bpel_app
       bpel

Table 9-2 Summary of the Oracle SOA Suite Command-Line Upgrade Tool Arguments

Command-Line Argument Description

-Dsource

The fully-qualified name and path for the directory where the Oracle SOA Suite 10g project files reside.

For Oracle BPEL Process Manager projects, this can be the bpel folder, the parent directory that hosts the bpel folder.

For Oracle Enterprise Service Bus projects, this can be the Oracle Enterprise Service Bus project folder.

-Dtarget

The fully-qualified name and path for the directory that will contain the upgraded project files.

The Oracle SOA Suite Command-Line Upgrade Tool upgrades your Oracle BPEL Process Manager project files, and generates new, upgraded files in a subdirectory of the target directory specified in this argument.

-DappName

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:

    ORACLE_HOME/upgrade/logs
    

9.4.8.5 Combining Multiple BPEL Projects Into a Single Composite with the Oracle SOA Suite Command-Line Upgrade Tool

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.

For example:

ant -f ORACLE_HOME/bin/ant-sca-upgrade.xml
    -Dsource "sourceDir1:sourceDir2"
    -Dtarget targetDir
    -DappName app_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.

9.4.8.6 Upgrading Oracle Enterprise Service Bus (ESB) Projects with the Oracle SOA Suite Command-Line Upgrade Tool

The Oracle SOA Suite Command-Line Upgrade Tool can also be used to upgrade ESB projects to Oracle Mediator 11g.

To upgrade an ESB project, use the instructions in Section 9.4.8.4, "Upgrading BPEL or ESB Projects with the Oracle SOA Suite Command-Line Upgrade Tool", but be sure to use the mediator argument, as follows:

ant -f ORACLE_HOME/bin/ant-sca-upgrade.xml 
    -Dsource sourceDir 
    -Dtarget targetDir 
    -DappName app_name
    mediator

9.4.8.7 Upgrading Domain Value Maps (DVMs) and Cross References (XREFs) in the ESB Repository

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.

    For more information, see "Managing the MDS Repository" in the Oracle Fusion Middleware Administrator's Guide.

To upgrade your 10g domain value maps in the ESB repository perform the following tasks.

Task 1   Export the domain value map metadata to a ZIP file
  1. Change directory to the Oracle Enterprise Service Bus Oracle home.

  2. Use the export script to export the metadata to a ZIP file.

    For example, on UNIX systems:

    ORACLE_HOME/export.sh metadata10g.zip
    
Task 2   Convert the ZIP file to an Oracle SOA Suite archive file

Use Apache Ant and the upgrade-xrefdvm target in the sca-upgrade.xml file to use the metadata ZIP file to generate an Oracle SOA Suite archive JAR file:

  1. Change directory to the Oracle SOA Suite 11g Oracle home.

  2. Use the following command to generate a SOA archive file, which will automatically be called sca_XrefDvmFiles10g_rev1.0.jar:

    ant -f ant-sca-upgrade.xml upgrade-xrefdvm
        -Dsource=location_of_the_zip_file
        -Dtarget=location_of_the_soa_archive
    

    For example:

    ant -f ant-sca-upgrade.xml upgrade-xrefdvm 
        -Dsource=$ORACLE_HOME/temp/upgrade/metadata10g.zip 
        -Dtarget=$ORACLE_HOME/temp/upgrade
    
Task 3   Import the archive file into MDS repository
  1. Start Oracle JDeveloper 11g and create a new application.

  2. Import the Oracle SOA Suite archive into a new SOA project:

    1. From the Oracle JDeveloper 11g File menu, select Import, then SOA Archive into SOA Project.

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

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

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

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

    For more information, see "Deploying and Using Shared Metadata Across SOA Composite Applications," in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

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.

9.4.9 Upgrading Oracle SOA Suite 10g Cross-References (XREF) Runtime Data to 11g

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.

Refer to the following sections for more information:

9.4.9.1 Procedure for Upgrading the XREF Runtime Data

To upgrade the cross reference runtime data from Oracle SOA Suite 10g to Oracle SOA Suite 11g:

  1. Locate the XREF 10g to 11g Data Upgrade Utility, and unzip it into a local directory.

    This utility can be found in the following directory when you download and unpack the Oracle Fusion Middleware Repository Creation Utility (RCU) archive file:

    RCU_HOME/rcu/integration/soainfra/sql/xref/XREF10gto11gDataUpgradeUtility.zip
    
  2. 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.

    For example:

    CREATE PUBLIC DATABASE LINK dblink10g 
        CONNECT TO 10g_db_user_name 
        IDENTIFIED BY 10g_db_password
        USING '(description=(address=(protocol=TCP)(host=10g_db_hostname)
                (port=10g_db_listening_port))(connect_data=(sid=10g_db_SID)))'
    

    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.

  3. 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
    
  4. Use a text editor to open the following SQL file:

    Upgrade10gXrefTo11gXref.sql
    
  5. Make the following edits to contents the file:

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

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

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

    Alternatively, the logs can be spooled to a file:

    spool on;
    spool path_of_local_file;
    @Upgrade10gXrefTo11gXref.sql
    spool off;
    

9.4.9.2 Additional Tasks and Considerations When Upgrading the XREF Runtime Data

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.