General rule engine concepts

Working memory

The working memory is a collection of objects that are seen by the rule engine. The collection is accessed as a set even when initialized with a list, for example, if the list contains duplicates, the working memory contains only distinct objects. The working memory contains only non-null items.

If the working memory is initialized with a list, the order of access does not necessarily follow the list order. However, the order is deterministic, for example, the reading order of the working memory is always the same when initialized with equivalent lists (same order and same elements).

Each rule engine in Decision Server is paired with a working memory.

For all the modes, you can initialize and inspect the working memory by using the following application programming interface (API).

For the RetePlus mode only, you can perform updates on the objects of the working memory by adding a statement in the action part of a rule or by using the API. The rule engine is aware of the objects that are in the working memory and any objects that are linked to them.

Note: The usage of the working memory is optional. You can use ruleset variables) instead.

Initialize working memory before engine execution

You can initialize the working memory with a collection via RuleflowEngineInput.

To use API from Java™ code, see Rule Designer reference.

RuleflowEngineInput ruleflowEngineInput = engine.createRuleflowEngineInput();
ruleflowEngineInput.setWorkingMemory(yourCollection);

Access working memory during execution

You can manage and inspect the working memory:

• In ILOG®® Rule Language (IRL), via the IlrContext object:

  • IlrContext#insert(java.lang.Object)

  • IlrContext#retract(java.lang.Object)

  • IlrContext#update(java.lang.Object) : has effect for retePlus mode only

  • IlrContext#updateContext() : has effect for retePlus mode only

• Using keywords:

  • insert

  • update : has effect for retePlus mode only

  • retract

  • modify : has effect for retePlus mode only

  For more information, see Rule Designer reference.

• Using ARL in B2X:

  You can access the working memory using API in java code (see Rule Designer reference). :

  • Collection<Object> getWorkingMemory(): Returns the working memory of the rule engine.
  • void insert​(Object o): Inserts an object into working memory.
  • void retract​(Object o): Removes an object from working memory.
  • void retractAll(): Removes all the objects from working memory.
  • void update​(Object o): Has effect for retePlus mode only

  See the Java documentation for more information: Rule Designer reference

Access working memory after execution

You can inspect the working memory after execution by using API in Java code. The method is getWorkingMemory() from Rule Designer reference:

 RuleflowEngineOutput ruleflowEngineOutput = engine.execute(ruleflowEngineInput);
Collection<Object> myWorkingMemory = ruleflowEngineOutput.getWorkingMemory();

For more information, see the Java documentation: Rule Designer reference

Rule Instance

A rule instance is created when the condition part of a rule is satisfied. The rule instance associates a rule with the bound objects that satisfy the rule condition.

Depending on the rule, there may be no object binding in a condition, for example, a rule without a condition.

In the following examples, you can see that a rule instance is a dynamic concept. The rule instance is produced by any combination of objects in the working memory that match the patterns specified in the rule. By contrast, a rule is a static concept.

Example without bound objects:

rule “rule1”:
then { 
add "Starting verification phase" to the messages of 'the loan';
}

This rule has no condition part, and the rule instance created from this rule does not contain bound objects: rule1().

Example with a ruleset variable

rule “rule1”:
when ‘the fish’ is green and the type of ‘the fish’ is “shark”
then { […] }

Suppose that, at execution time, “the fish” is F= new Fish(“toto”, color=green, type=”shark”). Since F satisfies the condition part, a rule instance is created from this rule using bound object F: rule1(F).

Example with objects from working memory

rule “rule1”:
when a Fish /* in the working memory */ is green and the type of a fish is “shark”
then { […] }

Suppose the working memory contains three Fishes { F1, F2, F3}, and only F1 and F3 satisfy the condition part of the rule. Two rule instance are created from this rule and bound objects F1 and F3: rule1(F1) and rule1(F3).

Example with two types of objects from the working memory

rule “rule1”:
when a Fish /* in the working memory */ is green and the type of a fish is “shark”
and
an Ocean /* in the working memory */ is “pacific”

Suppose the working memory contains { F1, F2, O1, O2, O3}. Suppose F1 and F2 match the conditions on the Fish and both O1 and O2 match the condition on the Ocean.

The following rule instances go into the agenda:

• rule1(F1,O1)
• rule1(F1,O2)
• rule1(F2,O1)
• rule1(F2,O2)

Example using the in generator

Here is an example using the in generator from an input ruleset variable of a type collection:

rule “rule1”:
when a Fish in ‘myRulesetVariableOfTypeCollection’
then { […] }

For the Fastpath and Sequential modes, the order of access for the elements in the collection follows the semantics of the collection, for example, set and then list.

For RetePlus mode, the order of access for the elements in the collection always follows the semantics of Set, even if the collection is an ordered list. The order of access is not guaranteed to be the one from the list but it is deterministic.

Agenda

The agenda stores an ordered list of rule instances . If the agenda is empty, execution stops. Consequently, the rule engine has to have some way of determining which rule in the agenda should be run.

In the agenda, rule instances are ordered to determine which rule instance should be run first.

Only the RetePlus and Fastpath modes use the agenda. For sequential mode, when a rule instance is created, it is immediately run.

For RetePlus mode, three criteria are used (see Agenda).