6 Working with Decision Functions
Use a decision function to call rules from a Java application, from a composite, or from a BPEL process.
This chapter includes the following sections:
6.1 Introduction to Decision Functions
A decision function is a function that is configured declaratively. A decision function performs the following operations:
-
Collects rulesets and other decision functions under a single executable umbrella
-
Handles the assertion of inputs as rule facts into the Oracle Business Rules Engine working memory
-
Collects the consequent actions to be executed
-
Runs rulesets
-
Returns results
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
A decision function is a function that is configured declaratively.
6.2.1 How to Add or Edit a Decision Function
You use Rules Designer to add a decision function.
-
In Rules Designer, select the Decision Functions navigation tab.
-
In the Decision Functions area, click Create....
-
Enter the decision function name in the Name field, or use the default name as Figure 6-1 shows.
Figure 6-1 The Decision Functions Area in Rules Designer
Description of "Figure 6-1 The Decision Functions Area in Rules Designer"
-
In the decision functions table, double-click the decision function icon. For example, double-click the decision function icon for DecisionFunction_1. This displays the Edit Decision Function dialog, as shown in Figure 6-2.
-
In the Name field, enter a name or accept the default value.
-
In the Description field, optionally enter a description.
-
In the Rule Firing Limit field, select unlimited. In some cases when you are debugging a decision function, you may want to enter a value other than
unlimitedfor the rule firing limit. For more information, see Section 6.3.2, "What You Need to Know About Rule Firing Limit Option for Debugging Rules". -
Select the appropriate decision function options:
-
Will be invoked as a Web Service: select whether the decision function will be invoked as a Web Service. For more information, see Section 6.3.4, "What You Need to Know About the Will Be Invoked As Web Service Option".
-
Check Rule Flow: when selected, this option specifies that the rule flow is checked to ensure that facts of the appropriate type are either explicit inputs to the decision function or are asserted by rules in the rule flow. However, when this is selected this does not always produce useful information; there are cases where facts can be asserted in Java code that uses the decision function, but this code might not be available at design time. In this case, validation warnings may produced with Check Rule Flow selected may not be useful.
-
Stateless: when selected specifies the decision function is stateless. For more information, see Section 6.3.5, "What You Need to Know About the Decision Function Stateless Option".
-
-
In the Inputs Table, 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 dropdown list.
-
Tree - When unselected, the input is asserted using the
assertfunction. When selected, the input is asserted using theassertTreefunction. When selected it is expected that the input object or objects are the root of an object tree that is connected in one-to-many relationships with other objects usingListor array type properties. For more information, see Section 4.8, "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
Listof objects and the assertion applies to each object in the inputList(java.util.List).
-
-
In the Outputs Table, 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 dropdown 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 Section 4.8, "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 Section 6.3.3, "What You Need to Know to About Decision Function Arguments".
-
-
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.
To edit an existing decision function:
-
In Rules Designer, select the Decision Functions navigation tab.
-
Select the decision function to edit and click the Edit icon 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.
To change the order of inputs:
-
In Rules Designer, select the Decision Functions navigation tab.
-
Select the decision function to edit and click the Edit icon 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.
To change the order of outputs:
-
In Rules Designer, select the Decision Functions navigation tab.
-
Select the decision function to edit and click the Edit icon 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.3 What You Need to Know About Decision Functions
A decision function is a function that is configured declaratively.
6.3.1 What You Need to Know About Using Undo Operation with Decision Functions
Rules Designer enables the option to undo and redo a delete operation on a decision function. You can perform this operation by clicking the Undo Decision Function Changes icon. However, if you perform the undo operation after deleting a decision function, this operation shows the decision function you deleted but can cause serious dictionary problems and can make the dictionary unusable.
In Rules Designer, do not use the Undo Decision Function icon after you delete a decision function.
6.3.2 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.
6.3.3 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: List<FactTypei> the input must be a
Listof objects and the assertion applies to each object in the inputList(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 unselected the input is asserted using the assert function. When Tree is selected, the input is asserted using the assertTree function. When Tree is selected it is expected that the input object or objects are the root of an object tree that is connected in one-to-many relationships with other objects using List or array type properties.
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 includes output for the decision function Outputs, depending on the number of output parameters. Table 6-1 describes the decision function output options.
Table 6-1 Decision Function Output Options Depending on Number of Outputs
| Output Parameters | Description |
|---|---|
|
0 |
The return value is null. |
|
1 |
Exactly 1 element it is returned. |
|
More than 1 |
The output then depends on the value of the list property:
|
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 "Using the Business Rule Service Component" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
6.3.4 What You Need to Know About the Will Be Invoked As Web Service Option
When the decision function option Will be invoked as a Web Service is selected, Oracle Business Rules generates an RL Language function which has input and output as XML datatypes. This option supports using a decision function from a Web Service.
This additional RL Language function has the following signature:
function <name>Service(T1 input1, ... Tn inputN, org.w3.dom.Node outputParentNode)
Ti expands depending on the value of the decision function Input List option for input, input i, such that:
-
List option unselected:
org.w3.dom.Element -
List option selected:
java.util.List<org.w3.dom.Element>
Input Element arguments are unmarshalled to result in InputFactType inputs. The resulting fact types are each marshalled to an Element and returned. These are passed to the generated function, which returns no result, an OutputFactType, or a List.
The marshalled output elements, if any, are added as child elements to the value passed in as the last argument of the function, outputParentNode. This node must be an Element, Document, or DocumentFragment.
For complete API information on DecisionFunction, see Oracle Fusion Middleware Java API Reference for Oracle Business Rules.
6.3.5 What You Need to Know About the Decision Function Stateless Option
A decision function supports either stateful or stateless operation. The Stateless checkbox in the Edit Decision Function dialog provides support for these two modes of operation.
By default the Stateless checkbox 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 deselected 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 deselected 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.