6 Working with Decision Functions

This chapter describes how to use a decision function to call rules from a Java application, from a composite, or from a BPEL process.

The chapter includes the following sections:

6.1 Introduction to Decision Functions

A decision function is a module of execution that can be invoked to reason on the inputs to arrive at outputs by applying a given ruleset or other decision functions.

A decision function contains the following declarations:

Input facts.
Rulesets and nested decision functions.
Output facts.

A decision function performs the following operations:

Asserts inputs as rule facts into the Oracle Business Rules Engine working memory.
Runs rulesets configured in the current decision function and in nested decision functions in order.
Returns output facts from the Oracle Business Rules Engine working memory.

You can create a decision function to simplify the use of Oracle Business Rules from a Java application or from a BPEL process. In a decision function the rules you want to use can be organized into several rulesets, and those rulesets can be executed in a prescribed order. Facts may flow to the first ruleset, and this ruleset may assert additional facts that flow to the second and subsequent rulesets until finally facts flow back to the decision function as decision function output.

6.2 Working with Decision Functions

You use Rules Designer to add a decision function.

To add a decision function:

In Rules Designer, click the Decision Functions tab.
In the Decision Functions area, click the Create button.

A new Decision Function is created and an Edit Decision Function dialog is displayed, as shown in Figure 6-1.

Figure 6-1 Edit Decision Function Dialog

Description of "Figure 6-1 Edit Decision Function Dialog"
Enter a name for the Decision Function in Name field and a description in the Description field.
In the Rule Firing Limit field, select unlimited or an integer value. In some cases when you are debugging a decision function, you may want to enter a value for the rule firing limit. The Rule Firing Limit can also be used in primary rules processing when you want the execution to stop after a specified number of rules fire.

For more information, see What You Need to Know About Rule Firing Limit Option for Debugging Rules.
Select the appropriate decision function options:
- Rule Firing Limit is Error: is used to indicate whether the rule firing limit is an error condition or not. Clear the check box if this is a scenario where you want rules processing to stop after n number of rules fire. When cleared, the rule firing limit is honored, but not reported as an error.
  
  Select this check box if this is a scenario where you are using the rule firing limit as a way to, for example, prevent an infinite loop. The system throws an error when the firing limit is reached.
- Will be invoked as a Web Service: select whether the decision function will be invoked as a Web Service and provide the Web Service name.
- Check Rule Flow: Rule flow checking verifies the following to generate validation warnings:
  - Types required by rules executed by the decision function are either inputs to the decision function or asserted by other rules.
  - Types generated by rules executed by the decision function are either inputs to other rules or outputs to the decision function.
    
    Rule flow checking might not identify rule flow issues spanning Java code that is used in rules. In such cases, the warnings can be ignored by turning off rule flow checking.
- Stateless: when selected, this option specifies that the decision function is stateless. For more information, see What You Need to Know About the Decision Function Stateless Option.
In the Inputs tab, click Add to add inputs. For each input in the Inputs Table, select the appropriate options:
- Name - enter an input name and press Enter or accept the default name.
- Fact Type - select the appropriate fact type from the list.
- Tree - When cleared, the input is asserted using the assert function. When selected, the input is asserted using the assertTree function. When selected, all objects referenced by the root object(s) are asserted. For more information, see Working with Tree Mode Rules.
- List - When unselected, the input must be a single object and the assertion applies only to that single input object. When selected, the input must be a List of objects and the assertion applies to each object in the input List (java.util.List).
- Description - Description of the input.
In the Outputs tab, click Add to add outputs. For each output in the Outputs Table, select the appropriate options:
- Name - enter an output name and press Enter or accept the default name.
- Fact Type - select the appropriate fact type from the list.
- Tree - When selected, this option sets a flag that enables certain design-time decision function argument checking. For an output argument, this option has no effect on runtime behavior. However, at design time in the case where several decision functions are called in a sequence, it is useful to notate explicitly that the output of one decision function is a tree. This implies that the input of another decision function in the sequence is expecting a tree as an input. For more information, see Working with Tree Mode Rules.
- List - When unselected the output is a single object. When selected the output is a group of objects. For more information on the behavior of the List option on an output argument, see What You Need to Know to About Decision Function Arguments.
- Description - Description of the output.
Note:

The visible attribute of a fact type controls whether a fact can be matched by a rule or can be asserted. Non-visible fact types are visible when they are part of a visible fact type, or a variable.

When inputs or outputs of a decision function are non-visible fact types, then a visible wrapper fact type is generated for the non-visible inputs named DF.in and a visible wrapper fact type for the non-visible outputs named DF.out.
For example, if i is an input of type int and o is a output of type int, then the following rule copies input to output:
```
 IF 
        DF.in != null 
 THEN 
        assert new DF.out(o: DF.in.i)
```
If you do not reference DF.in or assert DF.out, a rule flow warning occurs.
In the Initial Actions tab, you can add actions that could be used to change input facts before they are asserted, change the ruleset stack, set the effective date, or even assert output facts. These actions could be used instead of rules, or to "set up" the environment for running rules.

Consider a situation where a decision function (DF1) calls another decision function (DF2) using the Initial Actions tab. DF1 is configured to push Ruleset1 to the ruleset stack. DF2 is configured to push Ruleset2. In DF1, before the initial actions are executed, Ruleset1 is pushed to the ruleset stack. Then, when DF2 is called, Ruleset2 is also pushed. So when rules start running, rules from both rulesets fire because of the ruleset stack. If you want to push Ruleset2 (because in the initial actions, you are calling DF2), you can use initial actions in DF1 to clear the ruleset stack before calling DF2, and push Ruleset1 on the stack after calling DF2.

You can add any required action ranging from assert, call, modify to even conditional actions such as if, else, elseif, while, for, if (advanced), and while (advanced) as shown in Figure 6-2.

Figure 6-2 Adding Initial Actions

Description of "Figure 6-2 Adding Initial Actions"

Note:

If decision function DF1 contains DF2 in the Rulesets & Decision Functions tab, then DF2 may not have any initial actions.

The if (advanced) and while (advanced) conditional actions accept only boolean values. For each of the action conditions, you can add different test form types.
In the Rulesets and Decision Functions area, use the shuttle to move items from the Available box to the Selected box.
Select an item in the Selected box, and click Move Up or Move Down as appropriate to order the rulesets and the decision functions.

6.2.1 How to Edit an Existing Decision Function

To edit an existing decision function:

In Rules Designer, click the Decision Functions tab.
Select the decision function to edit and click the Edit button or double-click the decision function icon.
Edit the appropriate decision function fields in the same manner as you would when you add a decision function.

6.2.2 How to Change the Order of Inputs

To change the order of inputs:

In Rules Designer, click the Decision Functions tab.
Select the decision function to edit and click the Edit button or double-click the decision function icon.
Select the input argument you want to move. Click either Move Up or Move Down to reorder the input argument.

6.2.3 How to Change the Order of Outputs

To change the order of outputs:

In Rules Designer, click the Decision Functions tab.
Select the decision function to edit and click the Edit button or double-click the decision function icon.
Select the output argument you want to move. Click either Move Up or Move Down to reorder the output argument.

6.2.4 How to Edit a Decision Function

To edit a Decision Function

In Rules Designer, click the Decision Functions tab.
Select the Decision Function you want to edit and click the Edit icon.

The Edit Decision Function dialog is displayed.
Make necessary changes using the process that you have used for adding a new Decision Function.

6.3 What You Need to Know About Rule Firing Limit Option for Debugging Rules

The Rule Firing Limit allows you to set the maximum number of steps (rule firings) that are allowed at runtime.

Using this option and specifying a value other than unlimited can help you debug certain rule design problems and in some cases might help prevent java.lang.OutOfMemoryError errors at runtime. This is can be useful when debugging infinitely recursive rule firings.

When you choose a value other than unlimited, and choose Rule Firing Limit is Error, the system throws an error once the limit is reached.

6.4 What You Need to Know to About Decision Function Arguments

Oracle Business Rules generates a corresponding RL Language function for each decision function.

The signature of a generated decision function is similar to:

function <name>(InputFactType1 input1, ... InputFactTypeN inputN) returns List

In a decision function, each parameter is generated depending on the List option, with the decision function input, as follows:

Input argument, List option unselected: for FactTypei the input must be a single object and the assertion applies only to that single input object.
Input List option selected: for List<FactTypei> the input must be a List of objects and the assertion applies to each object in the input List (java.util.List).

The generated RL Language function includes calls either to assert or assertTree for each argument, depending on the decision function Input option, Tree. When Tree is cleared, the input is asserted using the assert function. When Tree is selected, the input is asserted using the assertTree function. When selected, all objects referenced by the root object(s) are asserted.

For the decision function selected rulesets, as specified in the Rulesets and Decision Functions area Selected box, the generated RL Language function includes a call to run() with the selected rulesets in the selected ruleset stack order.

The generated RL Language function returns a list. The list has an element for each decision function output in order. If the output is declared to be a list, then the corresponding element is a list. However, if the output is not declared to be a list, then the corresponding element is the output fact or null (if there is no output fact of the declared type). If an output is not declared to be a list, and more than one output fact of the specified type is found in the working memory of Oracle Business Rules Engine, then an exception is thrown.

After you edit a decision function, for example, to change or add inputs and outputs, the changes are visible in BPEL for new Business Rule activities. However, the changes are not visible to existing Business Rule activities. For more information, see "Getting Started with Oracle Business Rules" in the Developing SOA Applications with Oracle SOA Suite.

6.5 What You Need to Know About the Decision Function Stateless Option

A decision function supports either stateful or stateless operation. The Stateless check box in the Edit Decision Function dialog provides support for these two modes of operation.

By default the Stateless check box is selected which indicates stateless operation. With stateless operation, at runtime, the rule session is released after each invocation of the decision function.

When Stateless is cleared, the underlying Oracle Business Rules object is kept in the memory of the Business Rules service engine, so that it is not given back to the Rule Session Pool when the operation is finished. A subsequent use of the decision function re-uses the cached RuleSession object, with all its state information from the previous invocation. Thus, when Stateless is cleared, the rule session is saved for a subsequent request and a sequence of decision function invocations from the same process should always end with a stateless invocation.