ruletask

The ruletask keyword declares a rule task.

Purpose

The keyword used to declare a rule task.

Context

At the top level of rulesets

Syntax

ruletask ruleTaskName 
{
   [property propertyName = value;] 
   [algorithm = default|sequential;] 
   [matchedclasses = matchedClasses] 
   [iterator = value;] 
   [ordering = dynamic|sorted|literal;] 
   [firing = allrules|rule;] 
   [firinglimit = integer value;] 
   [agendafilter = agendaFilter] 
   [initialaction {action1 ... actionm}] 
   [finalaction {action1 ... actionn}] 
   [completionflag = value;] [scope = scope]
   [body body]
};  
matchedClasses is given a value in one of two ways:
matchedclasses = {class1, class2, ..., classn}
matchedclasses = value;
agendaFilter is defined in one of two ways:
agendafilter = filter(?instance) {action1 ... actions}
agendafilter = value;
body is defined in one of three ways:
body {ruleName1, ruleName2,..., ruleNamep}
body = select(?rule) {action1 ... actionq}
body = dynamicselect(?rule) {action1 ... actionr}

Description

A rule task is one of the three kinds of tasks available in a ruleflow. A rule task lists the rule or rules that define the rule task.

Note:

  1. The ruleflow syntax is described in Grammar specification.

  2. If a formal comment (/**...*/) precedes the task definition, it is saved so that you can retrieve it later using the API.

A rule task can have the following attributes:

  • property

    Use this attribute to define a user property on the task. The engine does not interpret this property. You can retrieve its value by defining API class and methods.

  • algorithm

    The value that follows this keyword indicates which execution mode is used to execute the rules: the RetePlus mode (the algorithm value is then default, which is its default value) or the sequential mode (the algorithm value is sequential).

  • matchedclasses, iterator

    Deprecated feature:

    Deprecation icon iterator and matchedclasses keywords and ilrTupleIterator interface in the sequential algorithm are deprecated as of V8.6.0.0. These features will be removed in a future release. See Deprecated and removed features for migration details.

    Use these keywords to configure the rule task when the rule engine execution mode is sequential because this execution mode does not use the working memory to know on which objects the rules are executed. These objects are given to the engine by tuples. The tuples can be either inferred from the working memory or specified through the iterator keyword. The value that follows the keyword is the instantiation of an object whose class implements the IlrTupleIterator interface. This iterator provides the tuples of objects on which the sequential execution mode is applied. In this case it is necessary to indicate how the tuples are formed, that is, the type of the objects that compose the tuple. This information is given as the value of the matchedclasses keyword. There are two ways to define the matched classes, either by giving the explicit list of classes names or by referencing a value whose type implements java.util.Collection. This collection object contains the references to IlrClass objects.

  • ordering, firing, firinglimit

    A rule task is designed to execute rules. You can set up some rule execution parameters, such as how the rules are ordered and how many rules are executed.

    The keyword ordering specifies how the rules are sorted.

    You can have rules sorted according to the following values:

    • dynamic: The rule instances are sorted in the agenda according to the traditional rules presented for the agenda.

    • sorted: The rules are sorted in decreasing order of static priority.

    • literal: The rules are ordered in the same way as they have been listed in the rule task body.

      Deprecated feature:

      Deprecation icon RetePlus literal, sorted, and priority ordering modes are deprecated as of V8.6.0.0. These features will be removed in a future release. See Deprecated and removed features for migration details.

  • agendafilter

    Use the agendafilter keyword in the rule task definition to filter the rules that are actually executed, according to specified criteria.

  • initialaction, finalaction

    You can define an initial action or a final action, or both, for a rule task. Initial actions are executed before the task body. Final actions are executed after the task body. They are composed of inline IRL code, such as IRL functions. They are similar to an IRL function with the void return type and with no arguments.

  • completionflag

    Deprecated feature:

    Deprecation icon Ruleflow completion flag is deprecated as of V8.6.0.0. This feature will be removed in a future release. See Deprecated and removed features for migration details.

    Use this attribute to specify a Boolean value that are evaluated after the execution of the task body is finished. If this Boolean value is true, then the task is completed, its final actions, if any, are executed, and the ruleflow execution continues. If the Boolean value returns false, the task is suspended: its final actions are not executed, the ruleflow execution is suspended, and the program returns to the caller of the ruleflow execution. When the ruleflow is executed again, it starts from this suspended task.

  • scope

    A scope defines the rules that can be used in the ruletask, before the optional selection defined in the body is applied. The use of a scope is optional.

  • body

    A rule task consists of a list of rules that compose its body. You can specify the rule list either by passing the rule names explicitly (extension), or by using select or dynamicselect keywords so that the list is computed from the code (comprehension). The given code must return a boolean value.

    The use of a task body is optional, but there must be at least a scope or a body.

Example

Example 1

In this rule task, the body consists of the rules DectectConnect4 and DetectGridFull. The rule ordering is set to literal: the order in which the rules are listed in the body is kept for the execution.

ruletask DetectConnect4
{
   ordering = literal;
   body = { DetectConnect4, DetectGridFull }
};
Example 2

In this rule task, the body is defined by comprehension. To compute the body, the code is executed for each rule in the ruleset. The rules for which the return value is true are part of the rule task body. The others are not part of the body.

The ordering here is set to sorted: the rules are sorted in decreasing order of static priority before being executed.

The firing value is set to rule: only one rule is executed among the rules that compose the body, even if more than one are eligible to be executed.

The initial actions are executed before the task body. If final actions are provided, they are executed after the task body.

ruletask ChooseMovePlayer1
{
   initialaction =
   {
      move = null;
   };

   body = select(?rule)
   {
      String ?task = ?rule.getProperties().getString("task","");
      return ?task.equals("ChooseMovePlayer1");
   }
   ordering = sorted;
   firing = rule;
};