Elements and types defined in the XML Schema can be imported into the data model so that instances of types can be created, asserted, modified, and retracted by rules. Most XML documents describe hierarchical information, where each element contains subelements. It is common for users to want to write individual rules based on multiple elements in this hierarchy, and the hierarchical relationship among the elements.

In Oracle Business Rules the default behavior when you assert a fact is to only assert the single fact instance, and none of the child objects it may reference in the hierarchy of subelements. When you create rules or a Decision Table it is often desirable to assert an entire hierarchy of elements based on a reference to a root element. Oracle Business Rules provides the assertTree action type that allows for a recursive assert for a hierarchy. For more information, see Working with Tree Mode Rules.

Before you can use the XML Schema definitions in a data model you must import the XML schema. This step generates the JAXB classes and makes the generated classes and packages associated with the XML schema visible in Rules Designer.

To import XML schema and add XML facts:

To work with an XML Fact, in Rules Designer open the Edit XML Fact dialog.

To display and edit XML facts:

The Edit XML Fact dialog includes the fields shown in Table 3-1.

If an XML schema changes in a project, the schema must be reimported into the Oracle Business Rules dictionary. When you reimport the schema, Oracle Business Rules uses JAXB to recompile all source schemas for every XML fact type and updates the XML fact type definitions with the updated XML schema definitions. You should reimport facts if you changed the schema or classes and you want to use the changed schema or classes at runtime.

To reimport XML facts:

After the reimport operation you need to correct any validation warnings that may be caused by incompatible changes (for example, the updated schema may include a change that removed a property that is referenced by a rule).

Keep the following points in mind when you work with XML Facts:

When XML Schema contain a restriction definition, this allows a user to restrict the types that are valid for use in an element. A common use of restriction is to define an enumeration of strings which can be used for an element, as shown in the XML Schema Restriction example below:

• <xs:simpleType name="status-type">
          <xs:restriction base="xs:string">
              <xs:enumeration value="manual"/>
              <xs:enumeration value="approved"/>
              <xs:enumeration value="rejected"/>
          </xs:restriction>
  </xs:simpleType>

  Oracle JAXB 2.0 maps a restriction to a Java enum type. When you use Rules Designer to import either a Java enum type or an element with an XML restriction, the static final fields representing the enums are available for use in expressions. Additionally, Oracle Business Rules creates a value set for each enum containing all of the enum values and null. For more information on value sets, see Working with Value Sets.

• There is a default version of the JAXB binding compiler supplied with Oracle Application Server. You can use a different JAXB binding compiler. However, to use a different JAXB binding compiler you must manually perform the XML schema processing and then import the generated Java packages and classes into the data model as Java Facts.

• You should reimport facts if you changed the schema or classes and you want to use the changed schema or classes at runtime. You should correct any validation warnings that may be caused by incompatible changes (for example, removing a property that is referenced by a rule). For more information, see How to Reload XML Facts with Updated Schema.

• Most users should not need to use the ObjectFactory or import it. If you do need to import and use the ObjectFactory, then use a different package name for every XML Schema that you import; otherwise the different ObjectFactory classes conflict.

• The use of XML schema with elements that have minOccurs="0" and nillable="true" has special handling in JAXB. For more information, see Why do XML Schema with xsd:string Typed Elements Import as Type JAXBElement?

• The default element naming conventions for JAXB can cause XML schema containing the underscore character in XML-schema element names to fail to compile. For more information, see Why Does XML Schema with Underscores Fail JAXB Compilation?

• There are certain restrictions on the types and names of inputs for the Decision Service. For more information, see How Are Decision Service Input Output Element Types Restricted?

• The built-in dictionary includes support for the Java wrappers Integer, Long, Short, Float, Double, BigDecimal, and BigInteger. These types can appear in XML Fact Types.

Before you can use Java Facts in rules and in Decision Tables, you must make the classes and packages that contain the Java Facts available to Rules Designer. To do this you use Rules Designer to specify the classpath that contains the Java classes, and then you import the Java Facts.

Java fact types allow methods with and without side effects to be imported. Side effects refer to expensive operations such as I/O, Database Query or web service and so on. When using Java classes as facts, remember the following about side effects:

• Rule and Decision Table conditions do not use methods with side effects.

• Actions can use all methods. Though side effects are not recommended, are permissible.

To import and define Java Facts:

To display or edit Java Facts after you import the Java Facts, use the Edit Java Fact dialog.

To display and edit Java facts:

The Edit Java Fact dialog includes the fields shown in Table 3-2.

When you define Java Facts you need to know the following:

• On Windows systems, you can use a backslash (\) or a slash (/) to specify the classpath in the Classpath area. Rules Designer accepts either path separator.

• Classes and interfaces that you use in Rules Designer must adhere to the following rules: If you are using a class or interface, only its superclass or one of its implemented interfaces may be made visible.

• When you specify the classpath you can specify a JAR file, a ZIP file, or a full path for a directory.

• When you specify a directory name for the classpath, the directory specifies the classpath that ends with the directory that contains the "root" package (the first package in the full package name). Thus, if the classpath specifies a directory, Rules Designer looks in that tree for directory names matching the package name structure.

  For example, to import a class cool.example.Test1 located in c:\myprj\cool\example\Test1.class, specify the classpath value, c:\myprj.

• You should reimport facts if you change the classes. After the reimport operation you may see validation warnings due to class changes. You should correct any validation warnings that may be caused by incompatible changes (for example, removing a property that is referenced by a rule).

You add RL Facts from the Facts navigation tab.

To define RL facts:

You add properties to RL Facts using the Edit RL Facts dialog.

To display and edit RL facts and add RL fact properties:

1. In Rules Designer, select the Facts navigation tab.

2. In the RL Facts tab, double-click the icon for the RL Fact to display or edit the fact. This displays the Edit RL Fact dialog, as shown in Figure 3-6.

   Figure 3-6 Edit RL Fact Dialog

   
   Description of "Figure 3-6 Edit RL Fact Dialog"

3. To add RL Fact properties, on the Edit RL Fact dialog in the Properties area, click Create.

   1. In the Name field, enter the property name.

   2. In the Type field, select a type from the list or enter a property type.

   3. To associate a value set with the property, from the list in the Value Set field, select a value set.

   4. To associate an initial value with the property enter a value in the Initial Value field.

4. Add additional properties by repeating these steps, as required.

5. Click OK.

When you add properties to RL Facts using the Edit RL Facts dialog, in the Properties area the Initial Value field provides a list of possible values as shown in Figure 3-7.

Figure 3-7 Setting RL Fact Property Initial Value

Description of "Figure 3-7 Setting RL Fact Property Initial Value"

When you are working with some fields in Rules Designer, the initial values list or other lists may be empty. In this case the list is an empty box. Thus, when Rules Designer does not find options to assist you in entering values, you must supply a value directly in the text entry area or click the Expression Builder button to display the expression builder dialog.

When an ADF Business Components view object is imported, an ADF Business Components fact type is created which has a property corresponding to each attribute of the view object.

To add ADF Business Components facts:

In the classpath list shown in the Search Classpath area in the Create ADF Business Components Fact dialog one of the listed classpaths allows you to see the view object definitions available in your project. In this dialog you only need to click Add to Classpath when you need to use a classpath that is not available to your project (this case should be very rare).

ADF Business Components Facts can include a circular reference. When this warning is shown in the Business Rule validation log you need to manually resolve the circular reference. To do this you must clear the Visible check box for one of the properties that is involved in the circular reference.

Each ADF Business Components fact type contains a property named ViewRowImpl that references the oracle.jbo.Row instance that the fact instance represents and a property named key_values which points to an oracle.rules.sdk2.decisionpoint.KeyChain object that may be used to retrieve the set of key-values for this row and its parent rows.

When working with ADF Business Components Facts you should know the following:

• Relationships between view object definitions are determined by introspection of attributes on the View Definition, specifically, those attributes which are View Link Accessors.

  The ADF Business Components fact type importer correctly determines which relationships are 1-to-1 and which are 1-to-many, and generates definitions in the dictionary accordingly. For 1-to-many relationships the type of the property generated is a List, which contains facts of the indicated type at runtime.

• It is not possible to use ADF Business Components fact types which have cyclic type dependencies. These cycles must be broken by the clearing the Visible check box for at least one property involved in the cycle.

• ADF Business Components fact types are not Java fact types and do not allow invoking methods on any explicitly created implementation classes for the view object.

  If you need to call such methods then add the view object implementation to the dictionary as a Java fact type instead of as an ADF Business Components fact type. In this case, all getters and setters and other methods become available but the trade-off is that related view objects become inaccessible and, should related view object access be required, these relationships must be explicitly managed.

• Internally, ADF Business Components fact types are instances of RL fact types.

  Thus, you cannot assert ADF Business Components view object instances directly to a Rule Session, but must instead use the helper methods provided in the MetadataHelper and ADFBCFactTypeHelper classes. For more information, see Oracle Fusion Middleware Java API Reference for Oracle Business Rules.

A list of values value set lets you specify the type and the list of values or ranges for the value set. For more information, see What You Need to Know About List of Values Value Sets.

To define a list of values (LOV) global value set:

You can control rule ordering in a Decision Table by changing the relative position of the values or ranges in an LOV value set associated with a condition expression in a Decision Table.

A list of ranges value set lets you specify the type and the endpoints for values or ranges in the value set. For more information, see What You Need to Know About Range Value Sets.

To define a list of ranges (range) global value set:

When you import an XML schema, if the XSD contains enumeration values Rules Designer automatically creates an enumerated type value set for each enumeration. Although enumerated type value sets are read-only, you can change the order of values.

For more information, see What You Need to Know About XML Facts.

To define an enumerated type (enum) value set from XML types:

You can control rule ordering in a Decision Table by changing the relative position of the values in an enum value set associated with a condition expression in a Decision Table.

When you import a Java enum, Rules Designer automatically creates an enumerated type value set for each Java enum. Although enumerated type value sets are read-only, you can change the order of values.

To define an enumerated type (enum) valueset from Java facts:

You can control rule ordering in a Decision Table by changing the relative position of the values or ranges in an enum value set associated with a condition expression in a Decision Table.

In a Decision Table, the order of the values in a value set associated with a condition expression determines the order of the condition cells, and thus the order of the rules. You can control rule ordering in a Decision Table by changing the relative position of the values in a list of values value set associated with a condition expression; however, you cannot reorder ranges.

Figure 3-11 shows a value set definition in Rules Designer for a value set named colors using a list of values.

Figure 3-11 Value Set Definition Using List of Values

Description of "Figure 3-11 Value Set Definition Using List of Values"

As shown in Figure 3-11, by default with a List of Values value set there is a value otherwise included with the list of values (LOV). This value, otherwise, is distinct from all other values and matches all values of the type that have no other value or range. Thus, with otherwise in the list of values a condition expression that uses the value set can handle every value and provides a match for every value of the specified type, where a match is either a defined value or the otherwise value. The otherwise value cannot be removed from an LOV value set but it can be excluded by clearing the Allowed in Actions check box (when otherwise is excluded an attempt to assign any value that is not in the list of values in the value set causes a validation warning).

Table 3-3 shows the value set values that Rules Designer supports for LOV value sets.

When you add a value or range to a List of Ranges value set, the value is calculated based on the currently selected value and the next highest value. When you change the endpoint value the value is automatically sorted in the value set; thus, it does not matter where a new range is added. However, it is possible for Rules Designer to not have values between the current value set endpoint value and the endpoint value. In this case, Rules Designer shows a validation warning of the following form:

RUL-05849: Valueset has duplicate bucket value "4999"

To correct this problem you must modify value endpoints to remove the duplicate value.

Table 3-4 shows the types Rules Designer supports for Range values.

Note the following conventions for the Range field:

• Logical operator: specifies a range with respect to positive or negative infinity. For example, ">=25" means "from 25 to positive infinity" and "<18" means from negative infinity up to but not including 18.

• Square bracket "[": specifies a range that includes this end point value. For example, "[18..25)" means "from 18 up to but not including 25".

• Round bracket ")": specifies a range that excludes this end point value. For example, "(18..25]" means "over 18, not including 18, up to and including 25".

When you define values or ranges in a value set you might define some ranges or values corresponding to non-permissible values. For example, in a value set for driver ages you would typically not allow a value that contains values less than 0. Thus, when a fact with driver data includes an age property associated with a driver ages value set, then you should not be able to create or modify a fact that has the age property set to a value such as -1. In a value set you select Allowed in Actions for valid values and clear this option for invalid values.

The value set option Include Disallowed Values in Tests allows you to include all the values, whether Allowed in Actions is selected or not, in Decision Table conditions and in rule tests. By including all values or ranges you can explicitly test for illegal values. Using the option Include Disallowed Values in Tests you can handle two possible cases:

1. The input data for the Oracle Business Rules Engine is clean and does not contain invalid data (such as a negative age). In this case, you should clear the Include Disallowed Values in Tests. Note: the reason you do not want to make age < 0 an Allowed in Actions is this provides design time validation warnings if you try to create an action that uses an invalid value, such as the following: modify(driver, age: -1)). For more information, see Using Value Sets as Constraints for Options Values in Rules.

2. You want to consider excluded values in rule tests and in Decision Tables. In this case, you should select Include Disallowed Values in Tests. This is useful when the input data for the Oracle Business Rules Engine may not be clean and may contain invalid data (for example an invalid negative age). A Decision Table that provides actions for all value sets could include cases for excluded values and provide an appropriate action, such as asserting an error fact. To handle this you could either select the Allowed in Actions field for every value in the value set, or, leave the Allowed in Actions field configured as is and select the Include Disallowed Values in Tests field. Using the Include Disallowed Values in Tests field is not only convenient, you do not need to reconfigure every value, it also preserves the configuration of Allowed in Actions so that you can easily reuse this value set to handle the first case (when you clear Include Disallowed Values in Tests).

When you enter a value in a value set, the value you supply must be valid for the type specified for the value set. If the value you enter is not valid for the value set type, Rules Designer makes the value you supply a string by adding quotation marks. Adding quotation marks is the only way to make a legal literal when the user provided data is not appropriate for the specified type. For example, if you add an int type LOV value set, and then supply a value 2.2, Rules Designer shows a warning such as the following:

RUL-05833: Invalid characters "2.2" in value

To fix this problem either enter a valid value for the value, for example in this case the value 2, or change the type of the value set.

For an additional example, when you enter a value for a value, for example if you enter a value with value set with data type short and add a value with the value 999999, Rules Designer assigns this the value "999999". The maximum value for a short is 32767. In this case you see a warning related to the value, similar to the previous example, because a String is not a valid value for a value set with data type short. The solution to this is to enter appropriate values for all values (in this example, enter a value less than or equal to 32767).

To prepare for creating Decision Tables, you can associate a global value set with fact properties in the data model.

To associate a value set with a fact property:

To prepare for creating Decision Tables you can associate a global value set with functions in the data model.

To associate a value set with a function return value:

To prepare for creating Decision Tables, you can associate a global value set with global values in the data model.

To associate a value set with a global value: