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"
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
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.
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 |
---|---|
|
Specify one of these strings to indicate the type of the origin repository. |
|
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. |
|
Specifies the destination directory in which the migrated dictionaries are placed. The migrated dictionaries are placed in a directory structure constructed with the For example, dir-name/dest-pkg/dest-dict-name.xml The |
|
Specifies the classpath to use for importing Java fact types during migration. |
|
Specifies the schema directory which contains all schemas used in XML fact types. |
|
Specifies the directory to generate JAXB classes into when importing schemas. |
|
Migrate all dictionaries in the origin repository. Either use |
|
Do not use with the Specifies the name of the dictionary to be migrated. |
|
Do not use with Specifies the version of dictionary to be migrated. |
Table B-2 Optional Migrate Rule Repository Options
Option | Description |
---|---|
|
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 |
|
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 |
Table B-3 WebDAV Only Migrate Rule Repository Options
Option | Arguments and Description |
---|---|
|
Argument specifies the Oracle Wallet file containing the WebDAV authentication information. |
|
When a proxy is involved, this option is required. Argument specifies the host to use as proxy for WebDAV access, if necessary. |
|
When a proxy is involved the argument specifies the port to use on proxy host for WebDAV access, if necessary. |
Using the MigrateRuleRepository
programmatic interface with Oracle Business Rules SDK. Note that most migration scenarios require that you perform manual migration tasks.
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
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:
In the Application Name field, enter an application name. For example, enter MigrateApplication
.
Enter or browse for a directory name, or accept the default.
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
.
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
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
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.
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
Repeat from step 10 for the remaining JAR files.
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
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
Click OK.
Oracle JDeveloper displays the Java Class, as shown in Example B-1.
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
.
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 define characteristics of the dictionary that you want to migrate. Example B-3 shows a migration program setting typical 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.
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.
// 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
.
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.
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.
<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.6.0), 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:
Delete a fact type with alias "FactType1"
Import a new fact type.
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.6.0), 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.
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.6.0): 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".
For each free form RL function, re-write the RL to use Actions.
In 11g Release 1 (11.1.1.6.0) 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.
In the previous release, the only option for XML schema import was JAXB 1.0. In 11g Release 1 (11.1.1.6.0), 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) ...