Summary

A statement that creates an object and inserts it into the working memory. This keyword is used in rule actions or functions.

Syntax

insert [ event[(timeExpression)] | logical ] object | typeName[arguments]
[{statement1 ... statementn}] ;

Description

The insert statement is used in the action part of a rule and in a function. It may create a new object with the typeName[arguments], it may execute statements on the scope of the object, and then inserts the object into the working memory.

If a typeName is specified, typeName is the type of the created object, and arguments are the constructor arguments. If the arguments are not given, it means that the object is created with the default constructor. To allow the rule engine to apply the constructor, you must declare it as public in your Java code.

Optionally statements may follow the object to be inserted into the working memory. These statements operate implicitly on the inserted object. They are executed before the object is inserted into the working memory. If only a single statement is used, the braces ({}) are not required.

When an object is inserted into the working memory as an event, a timestamp is automatically associated with it. The timeExpression defines an integer value that is used as the timestamp when inserting an event.

The desired class (of which the object must be a constructor) may implement the IlrEvent interface. If the IlrEvent interface is not implemented, the IlrDefaultEvent class is used whenever an event object is added to the working memory.

An event object can be explicitly removed from the working memory using the retract statement or with the API method IlrContext.retract.

The insert keyword can be optionally followed by the keyword logical, indicating that the object is of a logical type. An object marked as logical invokes the Truth Maintenance System. A logical object has two properties: the object is unique, and the validity of the object is maintained.

The uniqueness of the object is specified using the equals method of the Java class Object, which must be redefined in your Java class (see below). First an object is created normally using the specified constructor. This object is then tested, using the equals method, to determine whether an object already exists in the working memory that equals this object.

Maintenance of a logical object means that as long as the condition part of a rule that justified the object remains true, the object is kept in the working memory. If the condition part becomes false, the object will lose a justification. A logical object that loses its last justification is automatically retracted from the working memory.

In order to use the Truth Maintenance System, the equals method of the Java class Object must be redefined in your Java class; for example:

public boolean equals (Object obj)
   {
      if (obj == null || !(obj instanceof className))
         return(false);
         className myObj = (className)obj;
         return (fieldName.equals(myObj.fieldName));
   }

As well, you must define a hashCode method:

public int hashCode()
   {
      return (fieldName.hashCode());
   }

After an object has been inserted into the working memory, the insertion may optionally execute a demon. To execute a demon, the class must implement the interface IlrAssertDemon and must define the method asserted. For example:

public void asserted(IlrContext context)
  {
   System.out.println("Asserted className object in memory
                      with fieldName: " + filedName );
   }

prints a message every time an object of the class className is inserted into the working memory.

Examples

integer v = new Integer(2);
insert v;
 
insert Integer(13)
   {
      System.out.println("Inserting the value: " + intValue());
   }

The first insert inserts the Integer object previously created into the working memory.

The second insert passes the value 13 as a parameter. The ILOG JRules engine then interprets the block of executable statements while considering that the statements apply to the current object. When the method intValue is encountered, it is considered as the call to the method intValue on the current object, which returns 13 as a result. Thus, the print statement prints out:

Inserting the value: 13 

and the object is then inserted into the working memory.

insert Form()
   {
       color=Red;
       shape=Circle;
   }

A constructor without parameters is called. The statement block is then executed. The fields color and shape of the class Form are assigned values before the object is inserted into the working memory.

Using logical objects:

rule CheckTemperature { 
   when { 
      Sensor(type==Temperature; value>150);
   }
   then {
      insert logical (new Alarm());
   }
};
rule CheckPressure {
   when {
       Sensor(type==Pressure; value>2);
   }
   then {
       insert logical Alarm();
   }
};

Our example shows how to manage alarms in a chemical plant. If the temperature is greater than 150, an alarm must be issued. If the pressure is greater than 2, the same alarm must be issued. Here we want to have a single alarm if both temperature and pressure are exceeded.

If the rule CheckTemperature is fired, an alarm is created. Since the object is logical, it is maintained by the condition of the rule. If the temperature changes and is no longer greater than 150, the alarm is automatically removed from the working memory. However, if the temperature does not change and the rule CheckPressure is fired, instead of inserting a new alarm, the existing alarm will be justified a second time, using the rule's condition part.

Note that with the insert statement there are two ways of writing the object to be inserted. Either use parentheses around the object with the keyword new preceding the object as in the first example, or without parentheses and without the keyword new, as in the second example.

See Also