when

The when keyword declares the condition part of a rule.

Purpose

This keyword is used to introduce the condition part of a rule which consists of one or more conditions that must be satisfied for the rule to be executed.

Context

Rule conditions

Syntax

when {
       [collect|evaluate|exists|not|wait] condition1 
        ...
       [collect|evaluate|exists|not|wait] condition2 
}

Description

A condition can be instantiated with objects in the working memory. Using a class name, the rule engine matches instances of that class, or instances of any derived class. The keyword not, exists, or evaluate can precede a condition.

Use conditions for the following purposes:

Match patterns with objects of the working memory to test their validity. For example, Car(color == blue) tests whether a Car object has a color field equal to the value blue.
Instantiate a rule variable with a field of an object in the working memory. For example, given a Car object in the working memory with a field color, the condition Car(?c:color) instantiates the variable ?c with the color of the car.
Bind a rule variable with an object of the working memory that fulfills the constraints of the condition. For example, ?c:Car(color == blue) return a Car object with the field color equal to blue to variable ?c. If no such object exists in the working memory, the condition fails.

For each rule, the cardinality of rule instances in the agenda equals the product of the number of matched instances for each condition of the rule. For example, suppose we have two classes, Depart and Destination, and for each, three city instances: Paris, New York, and Tokyo.

rule example
{ 
   when {
      Depart(?c1:city);
      Destination(?c2:city);
   }
   then {
      System.out.println("Possible city pairs are: "
                         + ?c1 + ":" + ?c2); 
   }
}

This rule generates nine instances of the rule in the agenda, including the three naive results such as Tokyo:Tokyo.

Example

Example 1

In this example, the first condition of the CarColor rule is true if a Car object exists with the field color equal to red. The second condition tests that no Car object exists with the field color equal to green. If both conditions are true, the action is done, printing the message There is a red car but no green car.

rule CarColor
{ 
   when {
      Car(color == red);
      not Car(color == green);
   }
   then {
       System.out.println("There is a red car but no green car.")   
   }
}

Example 2

In this example, the first condition matches a Request object, binding the three variables ?m, ?h, and ?l with the fields mark, highPrice, and lowPrice, respectively.

The rule CarsAvailableAtPriceRange searches for a car from the information supplied by the user. The rule has two condition statements and one action statement. To execute the action statement, the two condition statements must be fulfilled.

The second condition matches a UsedCar object, with the following constraints: the field mark equals ?m and the field price has a value that is between ?h and ?l. If a UsedCar object is found that fulfills these constraints, it is bound to the variable ?car. The action part of the rule prints out any car found, for example, A 1996 BMW 573i is available for you. The action part might print multiple cars because each UsedCar object fulfilling the constraints generates a separate rule instance. For more information on rule instances of the agenda, see Agenda).

rule CarsAvailableAtPriceRange {
   when {
      Request(?m: mark; ?h: highPrice; ?l: lowPrice );
      ?car: UsedCar(mark equals  ?m ; price < ?h & > ?l)
   }
   then {
      System.out.println("A " + ?car.year + " " + ?car.mark 
                + " " + ?car.model + " is available for you.");
   }
}