insert

The insert keyword inserts an object into the working memory.

Purpose

This statement is used in the action part of rules or in functions to create an object and insert it into the working memory.

Context

Functions or rule actions

Syntax

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

Description

The insert statement creates a new object with the typeName [arguments], executes statements on the scope of the object, and inserts the object into the working memory. When you specify typeName, you must specify the type of the created object and arguments are the arguments that you pass to the constructor. If you do not pass any arguments, 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 can follow the object to be inserted into the working memory. Such statements operate implicitly on the inserted object. They are executed before the object is inserted into the working memory. If the statement block contains only one statement, 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 expression defines an integer value that is used as the timestamp when an event is inserted.

You can remove an event object explicitly from the working memory by using the retract statement or the IlrContext. retract method.

Optionally, you can add the logical keyword after the insert keyword to indicate that the object is of a logical type. An object marked as logical calls the Truth Maintenance System. A logical object has two properties: the object is unique and its validity is maintained.

Note: The usage of the event (in rule actions) keyword is deprecated as of V7.5.
Deprecated feature:

Deprecation icon The Truth Maintenance System (TMS), the logical (in insert) IRL keyword and the insertLogical (object) method are deprecated in V8.6. These features will be removed in a future release. See Deprecated features for migration details.

To specify the uniqueness of the object, you must redefine the Java Object.equals method in your Java class (see the example below). The process goes on as follows:

  1. An object is created normally from the specified constructor.

  2. This object is then tested by the equals method to determine whether an object that equals this object already exists in the working memory.

    • If an existing object in the working memory equals the object, the new object is not inserted into the working memory. The existing object is set to have a new justification that corresponds to the condition part of the rule that has just been executed.

    • If no existing object in the working memory equals the object, the new object is inserted into the working memory. This object is then maintained by the condition part of the rule that inserted it.

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 loses a justification. A logical object that loses its last justification is automatically retracted from the working memory.

To benefit of the Truth Maintenance System, you must redefine the Java Object.equals method and define a hashCode method in your Java class, as follows:

public boolean equals (Object obj)
   {
      if (obj == null || !(obj instanceof className))
         return(false);
         className
            myObj = (className)obj;
         return (fieldName.equals(myOb
            j.fieldName));
   }
...
public int hashCode()
   {
      return (fieldName.hashCode());
   }
Note:

If more than one field discriminates the object, the equals and hashCode methods must apply to each field.

Optionally, after an object has been inserted into the working memory, you can have a daemon run on them. To execute a daemon, the class must implement the interface IlrAssertDemon and define the method asserted. For example, these code lines print a message every time a className object is inserted into the working memory:

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

Example

Here are three different ways of using the insert keyword.

Example 1

This example uses an insert statement to insert an object into the working memory and another to pass an object value.

integer v = new Integer(2);
insert v;

insert Integer(13)
   {
      System.out.println("Inserting the value: " + intValue());
   }

This example runs as follows:

  1. The first line creates an Integer object.

  2. The first insert statement inserts this object into the working memory.

  3. The second insert statement passes the value 13 as a parameter.

  4. The engine interprets the block of executable statements as applying 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.

  5. The print statement prints out: 

    Inserting the value: 13

    and the object is then inserted into the working memory.

Example 2

This example calls a constructor with no parameters, then executes the statement block. The code assigns values to the fields color and shape of the class Form before the object is inserted into the working memory. 

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

This example uses logical objects to manage alarms in a chemical plant.

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();
   }
};

The CheckTemperature rule issues an alarm if the temperature is greater than 150. The CheckPressure rule issues the same alarm if the pressure is greater than 2. Here, the purpose is to have a single alarm if both temperature and pressure are exceeded.

If the rule CheckTemperature is executed, an alarm is created. Because 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 executed, instead of inserting a new alarm, the code justifies the existing alarm a second time, based on the condition part of the rule.

In an insert statement, you can write the object to be inserted in either of the following ways;

  • Write the keyword new before the object and use parentheses around the object, as in the first example.

  • Use neither parentheses nor the new keyword, as in the second example.