B Upgrading Oracle Business Rules Dictionaries and Projects

You can migrate Oracle Business Rules dictionaries and projects from previous releases. Before you can use a dictionary created with Oracle Business Rules Release 10.1.3.x with Oracle Business Rules for Oracle Fusion Middleware 11g Release 1 (11.1.1), you must migrate the dictionary to the new dictionary format. Depending on how the Release 10.1.3.x dictionary was created, there are several possible migration paths to migrate a dictionary from Oracle Business Rules Release 10.1.3.x format to Oracle Fusion Middleware 11g Release 1 (11.1.1).

This appendix includes the following sections:

Section B.1, "Using Oracle JDeveloper to Migrate an Oracle Business Rules Dictionary".
Section B.2, "Using Rule Migrator Tool to Migrate an Oracle Business Rules Dictionary"
Section B.3, "Using MigrateRuleRepository with Oracle Business Rules SDK to Migrate a Dictionary"
Section B.4, "Oracle Business Rules Manual Migration Tasks"

B.1 Using Oracle JDeveloper to Migrate an Oracle Business Rules Dictionary

When a dictionary is part of a an application created in a 10.1.3.x BPEL Decision Service, you can migrate to the Oracle Fusion Middleware 11g Release 1 (11.1.1) dictionary format when you open the BPEL process in Oracle JDeveloper.

To use Oracle JDeveloper to migrate a dictionary:

Start Oracle JDeveloper, as shown in Figure B-1, this displays the Oracle JDeveloper start page.

Figure B-1 Creating an Application in Oracle JDeveloper

Description of "Figure B-1 Creating an Application in Oracle JDeveloper"
From the File menu select Open.
Navigate to your project and select Open.

JDeveloper invokes the Oracle BPEL Process Manager migration utility to convert the project, including its rules dictionary.
Examine the Messages - Log window for any errors.

In some cases, you may need to manually edit the migrated rules dictionary using the Oracle Business Rules Designer to complete the migration. For more information, see Section B.4, "Oracle Business Rules Manual Migration Tasks".
From the File menu select Save All.

B.2 Using Rule Migrator Tool to Migrate an Oracle Business Rules Dictionary

You can use the MigrateRuleRepository command-line tool to migrate a dictionary from 10.1.3.x to Oracle Fusion Middleware 11g Release 1 (11.1.1) format. Note that most migration scenarios require that you perform manual migration tasks because 10.1.3.x has concepts that have been superseded in Oracle Fusion Middleware 11g Release 1 (11.1.1) by updated and more powerful constructs. For more information on the manual migration tasks, see Section B.4, "Oracle Business Rules Manual Migration Tasks".

The command-line tool is a Java class called the following:

oracle.rules.tools.migrator.MigrateRuleRepository

It is located in the following directory inside the SOA Oracle home:

SOA_HOME/soa/modules/oracle.rules.migration_11.1.1/migrator.jar

To run the command-line tool, you must have a specific set of JAR files available in the classpath. The list of required JAR files and libraries is included in Section B.3.1, "How to Migrate a Dictionary with Oracle Business Rules SDK".

For example, to set the classpath and run the migrator on Linux:

> export CLASSPATH=required_jar_files
> java -cp $CLASSPATH oracle.rules.tools.migrator.MigrateRuleRepository OPTIONS

The following shows a sample MigrateRuleRepository command:

MigrateRuleRepository -all
       -origType FILE_REPO
       -origLocation /scratch/MyRepository
       -destLocation /scratch/MyMigratedDictionaries
       -importedClasspath /scratch/foo.jar:/scratch/myclasses
       -xsdDirectory /scratch/myschemas
       -xsdGeneration /scratch/jaxb_classes

Table B-1 lists the required MigrateRuleRepository command-line arguments. Table B-2 lists the optional MigrateRuleRepository command-line arguments. Table B-3 lists the WebDAV MigrateRuleRepository command-line arguments.

Table B-1 Required Migrate Rule Repository Options

Option	Description
`-origType` {`FILE_REPO` \| `WEBDAV_REPO`}	Specify one of these strings to indicate the type of the origin repository.
`-origLocation` origin-repo	Argument specifies the Release 10.1.3.x repository containing a dictionary to be migrated. This is specified either with string that is either a URL to a WebDAV repository or a file path.
`-destLocation` dir-name	Specifies the destination directory in which the migrated dictionaries are placed. The migrated dictionaries are placed in a directory structure constructed with the `-destlocation`, `-destPackageName` and `-destDictionaryName` arguments. For example, dir-name/dest-pkg/dest-dict-name.xml The `pkg-name` is migrated into directories created in dir-name.
`-importedClasspath` classpath	Specifies the classpath to use for importing Java fact types during migration.
`-xsdDirectory` schema-dir	Specifies the schema directory which contains all schemas used in XML fact types.
`-xsdGeneration` jaxb-class-destination	Specifies the directory to generate JAXB classes into when importing schemas.
`-all`	Migrate all dictionaries in the origin repository. Either use `-all`, or specify the `-origDictionaryName` and the `-origVersionName`
`-origDictionaryName` origin-dict	Do not use with the `-all` option Specifies the name of the dictionary to be migrated.
`-origVersionName` origin-version	Do not use with `-all` option. Specifies the version of dictionary to be migrated.

Table B-2 Optional Migrate Rule Repository Options

Option	Description
`-destPackageName` dest-pkg	Specifies the package name to use when saving the migrated result dictionary in Oracle Business Rules Oracle Fusion Middleware 11g Release 1 (11.1.1) format. The migrated dictionaries are placed in a directory structure constructed with the `-destlocation`, `-destPackageName` and `-destDictionaryName` arguments.
`-destDictionaryName` dest-dict	Specifies the dictionary name to use when saving the Oracle Business Rules Oracle Fusion Middleware 11g Release 1 (11.1.1) format result dictionary. The migrated dictionaries are placed in a directory structure constructed with the `-destlocation`, `-destPackageName` and `-destDictionaryName` arguments.

Table B-3 WebDAV Only Migrate Rule Repository Options

Option	Arguments and Description
`-originPasswordSource` webdav-password-src	Argument specifies the Oracle Wallet file containing the WebDAV authentication information.
`-originProxyHost` webdav-proxy-host	When a proxy is involved, this option is required. Argument specifies the host to use as proxy for WebDAV access, if necessary.
`-originProxyPort` webdav-proxy-port	When a proxy is involved the argument specifies the port to use on proxy host for WebDAV access, if necessary.

B.3 Using MigrateRuleRepository with Oracle Business Rules SDK to Migrate a Dictionary

Using the MigrateRuleRepository programmatic interface with Oracle Business Rules SDK. Note that most migration scenarios require that you perform manual migration tasks.

B.3.1 How to Migrate a Dictionary with Oracle Business Rules SDK

To migrate using Java with Oracle Business Rules SDK, you use the oracle.rules.tools.migrator.MigrateRuleRepository class.

In the following example, you migrate the dictionary in the how-to-rules-java sample located here: http://www.oracle.com/technology/products/ias/business_rules/index.html.

To migrate a dictionary using Oracle Business Rules SDK:

Start Oracle JDeveloper, as shown in Figure B-2, this displays the Oracle JDeveloper start page.

Figure B-2 Creating an Application in Oracle JDeveloper

Description of "Figure B-2 Creating an Application in Oracle JDeveloper"
In the Application Navigator, click New Application if no applications have been created, or if applications have already been created click Applications and from the drop-down list choose New Application.
In the Create Application wizard, enter the name and location for the new application:
1. In the Application Name field, enter an application name. For example, enter MigrateApplication.
2. Enter or browse for a directory name, or accept the default.
3. Enter an application package prefix or accept the default, no prefix.
  
  This should be a globally unique prefix and is commonly a domain name owned by your company. The prefix, followed by a period, applies to objects created in the initial project of an application.
  
  In this sample, you can use the prefix com.example.
4. For an Oracle Business Rules project, select Generic Application for the application template, as shown in Figure B-3.
Figure B-3 Adding the Migrate Application

Description of "Figure B-3 Adding the Migrate Application"
Click Next.
In the Create Generic Application wizard - Name your Generic project page, enter the name and location for the new project as shown in Figure B-4:
- In the Project Name field, enter an application name. For example, enter MigrateProject.
- Enter or browse for a directory name, or accept the default.
- On the Project Technologies tab, in the Available list, select Java and click Move to add it to the Selected area.
Figure B-4 Specifying Technologies in a Project

Description of "Figure B-4 Specifying Technologies in a Project"
Click Finish.
In Oracle JDeveloper, select the project named MigrateProject.
Right-click and from the drop-down list select Project Properties.
Select the Libraries and Classpath item.

Click Add JAR/Directory.

You must update your project classpath with the following JAR files.

Note that there may be a JAVA_HOME installed next to JDEV_HOME, in your ORACLE_HOME directory.

JAVA_HOME/lib/tools.jar
JDEV_HOME/soa/modules/oracle.rules.migration_11.1.1/migrator.jar
JDEV_HOME/soa/modules/oracle.rules.migration_11.1.1/rulesdk.jar
JDEV_HOME/modules/oracle.adf.model_11.1.1/jr_dav.jar
JDEV_HOME/modules/oracle.pki_11.1.1/oraclepki.jar
JDEV_HOME/soa/modules/oracle.rules_11.1.1/rl.jar
JDEV_HOME/soa/modules/oracle.rules.migration_11.1.1/webdavrc.jar

In the Add Archive or Directory dialog, select the required JAR file and click Select as Figure B-5 shows.

Figure B-5 Project Properties Dialog: migrator.jar

Description of "Figure B-5 Project Properties Dialog: migrator.jar"
Repeat from step 10 for the remaining JAR files.
Click Add Library.

You must add the following libraries to your project classpath:
- BC4J Client
- Oracle JDBC
- Oracle Rules
- Oracle XML Parser v2
- JAX-RPC Client
In the Add Library dialog, select the required library and click OK as Figure B-6 shows.

Figure B-6 Project Properties Dialog: Oracle Rules Library

Description of "Figure B-6 Project Properties Dialog: Oracle Rules Library"
Repeat from step 13 for the remaining libraries.
Click OK.
In Oracle JDeveloper, select the project named MigrateProject.
Right-click and from the drop-down list select New.
In the New Gallery, in the Categories area, select General.
In the New Gallery, in the Items area, select Java Class.
Click OK.
In the Create Java Class window, configure the following properties as shown in Figure B-7:
- Enter the Name value Migrate.
- Enter the Package value com.example.
- Check the following check boxes:
  - Public
  - <None>
  - Constructors from Superclass
  - Main Method
  Figure B-7 Creating the Migrate.java Class
  
  Description of "Figure B-7 Creating the Migrate.java Class"

Click OK.

Oracle JDeveloper displays the Java Class, as shown in Example B-1.

Example B-1 Code Created for New Migrate.java Class

package com.example;

public class Migrate {
    public Migrate() {
    }

    public static void main(String[] args) {
        Migrate migrate = new Migrate();
    }
}

Use the MigrateRuleRepository API to add code like that shown in Example B-2.

For more information about the MigrateRuleRepository API, see Section B.4.3, "What You May Need to Know About Manual Migration".

Example B-2 Migrate.java Completed

package com.example;
 
import java.io.PrintWriter;
 
import oracle.rules.tools.migrator.MigrateRuleRepository;
 
public class Migrate {
    public Migrate() {
        try {
 
         // Create a migrator instance
         MigrateRuleRepository conv = new MigrateRuleRepository();
         
         // Set the output buffer
         conv.setOutLog(new PrintWriter(System.out));
          
         // Set input properties (SDK format)
         conv.setOriginLocation("C:\\Temp\\how-to-rules-java\\dict\\CarRepository");
         conv.setOriginType(MigrateRuleRepository.FILE_REPO);
         conv.setOriginDictionaryName(MigrateRuleRepository.MIGRATE_ALL);
         conv.setOriginVersionName(MigrateRuleRepository.MIGRATE_ALL);
         conv.setImportedClassPath("C:\\Temp\\how-to-rules-java\\lib\\car.jar");
         
         // Set output properties
         conv.setDestinationLocation("C:\\Temp\\how-to-rules-java\\dict\\CarRepositorySDK2");
        
         conv.migrate();
            String results = conv.getTotalStats();
            System.out.print(results);
        }
        catch (Exception e)
        {
            System.out.print(e);
        }        
    }
 
    public static void main(String[] args) {
        Migrate migrate = new Migrate();
    }
}

If the repository you are migrating contains XML Fact Types, you need to specify the location of the schema file that defines these XML Fact Types, and also the output directory that JAXB should use when converting schema files into Java classes.

Since there are no XML Fact Types in this demo, these lines of code are not needed:
```
conv.setXSDLocation("C:\\Temp\\how-to-rules-java\\schemas"); // or other
       directory, as appropriate
conv.setXSDOutputDirectory("C:\\Temp\\how-to-rules-java\\jaxbOutput"); // or
       other directory, as appropriate
```
In the Application Navigator, right-click Migrate.java and select Make.
In the Application Navigator, right-click Migrate.java and select Run.
Examine the Messages - Log window for any errors.

In some cases, you may need to manually edit rules to complete the migration.
Retrieve the migrated dictionary from the destination location.

In this example, from C:\Temp\how-to-rules-java\dict\CarRepositorySDK2.

B.3.2 What You May Need to Know About the MigrateRuleRepository API

For complete details on the MigrateRuleRepository API, see the Oracle Fusion Middleware Java API Reference for Oracle Business Rules.

As shown in Example B-3, a typical migration program uses the MigrateRuleRepository API to set:

Input Properties
Output Properties

B.3.2.1 Input Properties

Input properties define characteristics of the dictionary that you want to migrate. Example B-3 shows a migration program setting typical input properties.

Example B-3 Input Properties

// Set input properties (SDK format)
conv.setOriginLocation( "C:\\scratch\\SDK1_Repository" );
conv.setOriginType(MigrateRuleRepository.FILE_REPO);
conv.setOriginDictionaryName(MigrateRuleRepository.MIGRATE_ALL);
conv.setOriginVersionName(MigrateRuleRepository.MIGRATE_ALL);

You must set the following mandatory input properties using MigrateRuleRepository method:

setOriginLocation to specify the fully qualified path to the rules dictionary to migrate.
setOriginType to specify the type of repository that contains the rules dictionary. You can choose any of the following constants:
- MigrateRuleRepository.FILE_REPO: the rules dictionary is stored in the host file system as a simple file.
- MigrateRuleRepository.WEBDAV_REPO: the rules dictionary is stored in a WebDAV-managed repository.
setOriginDictionaryName to specify the name of the dictionary contained by the specified rules dictionary to migrate. Specify either the dictionary name as a String or MigrateRuleRepository.MIGRATE_ALL to migrate all dictionaries contained by the specified dictionary.
setOriginVersionName to specify the version of the specified rules dictionary to migrate. Specify either the dictionary version as a String or MigrateRuleRepository.MIGRATE_ALL to migrate all versions of the specified dictionary.

You may use other MigrateRuleRepository methods to define optional input properties as required.

B.3.2.2 Output Properties

Output properties define characteristics of the Oracle Fusion Middleware 11g Release 1 (11.1.1) Oracle Business Rules dictionary that the MigrateRuleRepository class migrates to, given the input properties you specify (see Section B.3.2.1, "Input Properties"). Example B-4 shows a migration program setting typical input properties.

Example B-4 Output Properties

// Set output properties (SDK2 format)
conv.setDestinationLocation( "C:\\scratch\\SDK2_Migrated_Dictionaries" );

You must set the following mandatory output properties using MigrateRuleRepository method:

setDestinationLocation to specify the fully qualified file name of the new Oracle Fusion Middleware 11g Release 1 (11.1.1) Oracle Business Rules based rules dictionary.

You may use other MigrateRuleRepository methods to define optional output properties as required.

For example, by default, the new Oracle Fusion Middleware 11g Release 1 (11.1.1) Oracle Business Rules dictionary uses the same package name as that used in the original dictionary. To override this behavior, you can specify a new package name using MigrateRuleRepository method setDestinationPackageName.

B.4 Oracle Business Rules Manual Migration Tasks

Before you can use an a dictionary created with Oracle Business Rules Release 10.1.3.x, you must migrate it to the format required for Oracle Fusion Middleware 11g Release 1 (11.1.1). The easiest way to migrate a dictionary that is part of a Decision Service in a BPEL process is to use JDeveloper. Alternatively, you can migrate using the MigrateRuleRepository command-line tool. Certain migration scenarios require you to perform manual migration tasks.

B.4.1 How to Migrate JAXB 1.0 to JAXB 2.0

To take advantage of the significant usability improvements present in JAXB 2.0, you must perform the following migration tasks manually.

The most significant difference between JAXB 1.0 and JAXB 2.0 is the classes which are generated. JAXB 1.0 was created before Java 1.5 introduced annotations, so it relies on a series of interfaces and abstract classes. The default in Oracle Business Rules Release 10.1.3.x was to use JAXB 1.0. In Oracle Fusion Middleware 11g Release 1 (11.1.1), the default is to use JAXB 2.0. Rules Designer only allows XML schemas to be imported using the JAXB 2.0. Migrated dictionaries continue to use JAXB 1.0, but the schema cannot be modified or reimported as JAXB 1.0.

A migrated dictionary which uses JAXB 1.0 objects still works with Oracle Fusion Middleware 11g Release 1 (11.1.1). However, JAXB 2.0 provides significant new features and many improvements for working with Oracle Business Rules.

Consider the XSD fragment that Example B-5 shows.

Example B-5 XSD Fragment

<element name="foo">
  <complexType>
      <sequence>
        <element name="bar" type="string"/>
        <element name="baz" type="string"/>
      </sequence>
  </complexType>
  </element>

This element uses an anonymous complex type to define a data structure. JAXB 1.0 generates the following classes:

FooType
Foo extends FooType, javax.xml.bind.Element
FooImpl extends FooTypeImpl implements Foo
FooTypeImpl extends oracle.xml.jaxb.JaxbNode implements FooType

The only way to create instances of these classes is the static factory methods in ObjectFactory.

By contrast, JAXB 2.0 generates a single annotated class, Foo, which can be instantiated using either new or an ObjectFactory method.

In the previous release, rules were written using the FooType fact type, whereas in 11g Release 1 (11.1.1), they are written using the Foo fact type.

To migrate from FooType to Foo fact types, perform the following manual migration task.

To migrate JAXB 1.0 to JAXB 2.0:

Use Rule Migrator to migrate.

For more information, see Section B.2, "Using Rule Migrator Tool to Migrate an Oracle Business Rules Dictionary".
Delete all classes in SCA-INF/classes.
Record the aliases assigned to all of the fact types used in your rules.

For example, FooType fact alias "My Foo Type".
Delete from the data model the XML Fact Types you want to upgrade to JAXB 2.0.

This operation can result in a large number of validation warnings, one for every reference to the now-deleted fact types.

However, the SDK stores references to both the ID and String value of all referenced elements.

If the reference ID is set and it exists, then the String value is updated to reflect its current alias. So, if the alias of a fact type is changed, all of the places where that fact type is referenced get the new value because of the reference id.

If the element with the ID is removed from the dictionary, the String value retains the last known name of the referenced element. This allows you to, for example:
1. Delete a fact type with alias "FactType1"
2. Import a new fact type.
3. Set the alias of the new fact type to "FactType1" and all of the references to the deleted fact type automatically change to the new fact type.
Import the schema.

In 11g Release 1 (11.1.1), JAXB 2.0 is the default.
Set the alias of the fact type to the previous alias.

For example, change the alias of Foo to FooType.
Run validation on the dictionary.
If desired, set the alias of the fact type back to the original alias.

For example, change the alias FooType back to Foo.
Confirm that all of the references are now be updated.

B.4.2 How to Migrate RL Functions

In the previous release, the only option for creating a Function was to write free form RL. These functions relied on generated RL names, which have changed in 11g Release 1 (11.1.1): the RL names are now automatically computed from the alias so they are RL-compliant, instead of relying on the user to provide a valid name.

You must re-write any function which accesses globals to comply with this change by using Actions. It is easier to write functions using Actions because they are validated at design-time.

In Oracle Business Rules Release 10.1.3.x dictionaries that contain free-form RL functions, it was a common practice to refer to Java classes which were not in the data model. For example, many dictionaries include functions which use ObjectFactory to create instances of JAXB classes. In Oracle Fusion Middleware 11g Release 1 (11.1.1), to include this class in the data model you cannot simply reimport the schema and import ObjectFactory because it is imported as a JAXB 2.0 class. The solution in this case is to use the ObjectFactory class which is in the "classes" directory in your project from when the dictionary was migrated. This ObjectFactory class should be imported as a Java class and can then be referenced in Oracle Fusion Middleware 11g Release 1 (11.1.1) functions.

For more information, see Section B.4.3, "What You May Need to Know About Manual Migration".

To migrate RL functions:

For each free form RL function, re-write the RL to use Actions.

In 11g Release 1 (11.1.1) you may use Actions both in Function bodies and in rules. There are several new Action forms which in most cases eliminate the need for free form function bodies. Action forms available include:
- Call
- Assert and Assert new
- Retract
- Assign and Assign New
- Modify
- Synchronized
- Expression
- Assert
- If, Else If, and Else
- For and While
- Return, Throw, Try, Catch, and Finally
- RL
Validate your dictionary.

For more information, see "Understanding Decision Table Validation" in the Oracle Fusion Middleware User's Guide for Oracle Business Rules.

B.4.3 What You May Need to Know About Manual Migration

In the previous release, the only option for XML schema import was JAXB 1.0. In 11g Release 1 (11.1.1), Oracle Business Rules provides support for JAXB 1.0, but JAXB 2.0 is the default. If you choose to continue to use JAXB 1.0, generated RL may throw MultipleInheritanceException. For more information, see "JAXB 1.0 Dictionaries and RL MultipleInheritanceException" in the Oracle Fusion Middleware User's Guide for Oracle Business Rules.

The SDK does not do any validity checking on free form RL Function bodies. As a result, any errors in the functions are not revealed until the RL is executed. Example B-6 shows what such an error looks like in a BPEL process:

Example B-6 Invalid RL Function Runtime Error

[2008-10-01T04:52:15.043-07:00] [server_soa] [ERROR] [] [oracle.soa.services.rules] [tid: 35] [ecid:0000HmsG4oAEsHQ6ubV4EH18sYBt0000JA,0:2:100000051] [composite_name:ThreePattern] [component_name: CreditRatingRules] [component_instance_id:90558a4f-8781-4ac7-821c-49f46dd2f8fc] [composite_instance_id: 90033] <.>
Error caching the Decision Services metadata.[[
Error caching the decision services metadata for path
default/ThreePattern!1.0*c04f9ced-55ff-42fc-a6ee-f64a2055baf2/CreditRatingRules.
Check the underlying exception and correct the error. This is most likely due
to a rule modeling isssue. Validate the rule dictionary in rule designer and
fix any errors and warnings. Contact oracle support if error is not fixable.
ORABPEL-36109 Error caching the Decision Services metadata.
Error caching the decision services metadata for path default/ThreePattern!1.0*c04f9ced-55ff-42fc-a6ee-f64a2055baf2/CreditRatingRules.
Check the underlying exception and correct the error. This is most likely due to a rule modeling isssue. Validate the rule dictionary in rule designer and fix any errors and warnings. Contact oracle support if error is not fixable.
         at oracle.bpel.services.rules.impl.DecisionServiceCache.cacheDecisionServiceMetadata(DecisionServiceCache.java:1039)
        at
oracle.bpel.services.rules.impl.DecisionServiceCache.prepare(DecisionServiceCache.java:343)
        at
oracle.bpel.services.rules.impl.DecisionServiceImpl.preProcess(DecisionServiceImpl.java:1164)
...

Caused by: oracle.rules.rl.exceptions.UndefinedException: symbol'CreditRatingRules.rating_param' is undefined at line 25 column 8 in main
        at
oracle.rules.rl.exceptions.ExceptionFactory.createUndefinedException(ExceptionFactory.java:386)
        at oracle.rules.rl.analyze.Expr.qname(Expr.java:1742)
        at oracle.rules.rl.analyze.Expr.primary(Expr.java:814)
        at oracle.rules.rl.analyze.Expr.expr(Expr.java:195)
...