9 Considerations When Upgrading All Oracle SOA Applications

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:

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

• Accessing a Dictionary in the Development Environment

• Accessing a Repository in a Production Environment

• Generating RL Code

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);

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();}
     }
}

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);

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);

//init a rule session
String rsname = "vehicleRent";
String dmrl = dict.dataModelRL();
String rsrl = dict.ruleSetRL( rsname );

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

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
          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 comlpete, 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".

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

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

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