Summary

A left-hand side statement to construct a collection object. This keyword is used in rule conditions.

Syntax

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

Description

The collect statement is used 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 may contain tests on the class fields. The collection object may be bound to a variable for the scope of the rule. The expression is optional, but if provided, must return a collector object that implements three public methods: addElement, updateElement and removeElement. The collect statement may contain a list of tests on the collection object in the where part of the statement.

The collector object, declared by expression, must implement the interface IlrCollection and its three public methods: addElement, updateElement, and 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 default collector object of type IlrDefaultCollector is used (see the ILOG JRules API Reference documentation for details).

The where part of the statement may contain tests that the collection object must fulfill. It may be left empty. There are several methods, including the IlrCollection interface methods, that are provided by default for all collections: size(), isEmpty(), contains(), and elements() (see the ILOG JRules API Reference documentation for details).

Example

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 MusicCollector rule collects Music objects and stores them in an ItemCollector object.The first condition returns in variable ?s the objects of class Store that have the field domain equal to MUSIC. The variable ?c refers to the ItemCollector object. The constructor for the ItemCollector object takes as an argument a Store object. 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 matching this condition will be inserted into the object ItemCollector. For the collect statement to be true, there are two tests defined in the where part of the statement. The default method size() is used to test that the number of items in the collector is greater than 5, and the user defined method averagePrice() is used to test that the average price of the items is less 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 that refers to an enumeration of the elements of the ItemCollector object. The while statement is used to print the name field of the Store object and the corresponding title field of each Music object.

See Also