update

The update keyword updates an object.

Purpose

This keyword is used in the action part of rules or in functions to update a modified object in the working memory. You can use it in RetePlus mode to notify the rule engine of an object state change. The engine then matches the rules against the new object state, which can result in new rule instances being added to the agenda.

Context

Functions or rule actions

Syntax

update [refresh] object;

Description

You can define the object parameter as a variable or an expression that denotes an object associated with the current context or a specified context.

When an object is modified (for example, in a function or in Java™ code), the rules of the agenda might not be in a consistent state with respect to the new contents of the object. In such cases, you must use the update statement to notify the rule engine of the modification.

If the refresh keyword applies, rules that remain true or become true after the modification of the object are reinserted into the agenda. Without this keyword, only the rules that become true as a result of the modification are inserted into the agenda.

Note: In the decision engine you must add the com.ibm.rules.engine.repeatable property.

After an object has been updated in the working memory, the update statement can optionally execute a daemon. For this purpose, write a class that implements the interface IlrUpdateDemon and defines the method updated. For example, this method prints a message each time a className object is updated in the working memory:

public void updated(IlrContext context)
   {
      System.out.println("Updated a className object in
                         memory with fieldName: " + fieldName);
   }

Example

rule JobProcessing 
{
   priority = -?a;
   when {
      ?n:NewJob(?s:size;?p:priority);
      ?proc:Server(?a:activity; ?id:identifier);
   }
   then {
      retract(?n);
      insert( new Job(?s,?p,?id));
      ?a = ?a + ?proc.updateActivity(?n);
      update refresh ?proc;
   }
};

The JobProcessing rule assigns new jobs to servers based on the server activity level. The rule uses a dynamic priority that is equal to the negation of the activity level. The lower the activity level, expressed by the variable ?a, the higher the priority. Hence, the server with the lowest activity level executes first.

The rule has two conditions. The first condition matches an object NewJob which is returned by the variable ?n. This condition contains variable ?s, which returns the value of field size, and variable ?p, which returns the value of field priority. The second condition matches an object Server, referenced by the variable ?proc. This condition contains variable ?a, which returns the value of field activity, and variable ?id, which returns the value of field identifier.

The action part of the rule follows the keyword then and works as follows.

The first action applies the retract statement to the NewJob object, pointed to by variable ?n.
The second action applies an insert statement to a Job object with three fields, size, priority, and identifier, represented by the three variables ?s, ?p, and ?id. A new activity value is calculated by incrementing the activity ?a with the result of the method updateActivity. This method is called on the Server object pointed to by the variable ?proc.
Finally, the Server object is updated in the working memory using the update statement with the refresh keyword. Any rule matching a Server object in the condition part can be reinserted into the working memory.