collect

The collect keyword constructs a collection object.

Purpose

This statement is used to construct a collection object.

Context

Rule conditions

Syntax

[?variable:] collect [(expression)] collectionTarget
            [where (collectionTest1 ... collectionTestn)];

Description

Use the collect statement in the condition part of a rule to create a collection object. The collection object stores instances of the class collectionTarget that match the condition. This condition can contain tests on the class fields. The collection object can be bound to a variable for the scope of the rule. The expression is optional, but if provided, it must return a collector object that implements the IlrCollection interface, as shown in the example below. The collect statement can contain a list of tests on the collection object in the where part of the statement.

If a rule contains some conditions that are matched and a collect condition, the eligibility of the rule depends on the existence of a where statement, as follows:

Without a where statement, the rule is eligible to be executed, even if no object has been matched by collectionTarget. In other words, the rule is eligible and the collection object is empty.
With a where statement, the rule is eligible only if the where statement is evaluated to true.

The collector object, declared by an expression, must implement the IlrCollection interface and its public methods: IlrCollection#addElement, IlrCollection#updateElement, and IlrCollection#removeElement. The IlrCollection interface is defined as follows:

public interface IlrCollection {
   public void addElement(java.lang.Object element);
   public void updateElement(java.lang.Object element);
   public void removeElement(java.lang.Object element);
}

If the expression argument is left empty, a IlrDefaultCollector object is used.

The where part of the statement can contain tests that the collection object must fulfill. Or it can be left empty. The IlrCollection interface and IlrDefaultCollector class provide methods for all collections, such as size, isEmpty, contains, and elements.

Description

If the expression argument is left empty, a IlrDefaultCollector object is used.

The where part of the statement can contain tests that the collection object must fulfill. Or it can be left empty. The IlrCollection interface and IlrDefaultCollector class provide methods for all collections, such as size, isEmpty, contains, and elements.

Example

The MusicCollector rule collects Music objects and stores them in an ItemCollector object. The first condition returns in variable ?s the Store objects that have the field domain equal to MUSIC. The variable ?c refers to the ItemCollector object. The constructor for the ItemCollector object takes a Store object as an argument.

rule MusicCollector {
   when {
      ?s: Store(domain==MUSIC);
      ?c: collect(new ItemCollector(?s))
          Music(store==?s; category==JAZZ; 
          artist equals "Miles Davis";
          production > 1956 & < 1965)
          where ( size() > 5 && ItemCollector.averagePrice() 
                         < 15.0);
   }
   then {
      Enumeration ?enum = ?c.elements();
      while (?enum.hasMoreElements()) {
         Music ?cd = (Music)enum.nextElement();
         System.out.println("At " + ?s.name 
                         "you can find the title: " + ?cd.title);
      }
   }
}

The collectionTarget is the class Music with the following field values:

store equal to the result in ?s
category equal to JAZZ
artist equal to the string Miles Davis
production between the dates 1956 and 1965

Any object that match this condition is inserted into the ItemCollector object. For the collect statement to be true, two tests are defined in the where part of the statement. The default method size tests that the number of items in the collector is greater than 5and the user-defined method averagePrice tests that the average price of the items is lower than 15.

If the when part of the rule is true, the then part is executed. The variable ?c refers to the ItemCollector object. The first statement creates a variable ?enum which refers to an enumeration of the elements of the ItemCollector object. The while statement prints the name field of the Store object and the corresponding title field of each Music object.