8.2. How Rules Operate on Facts

Facts are domain model objects that BRMS uses to evaluate conditions and execute consequences. A rule specifies that when a particular set of conditions occur, then the specified list of actions must be executed. The inference engine matches facts against rules, and when matches are found, rule actions are placed on the agenda. The agenda is the place where rules are queued ready to have their actions fired. The rule engine then determines which eligible rules on the agenda must fire.

8.2.1. Rule files Accessing the Working Memory

The working memory is a stateful object that provides temporary storage and manipulation of facts. The working memory includes an API that contains the following functions that allow access to working memory from rules files:
  • update(object, handle)
    This method is used to tell the engine that an object has changed and rules may need to be reconsidered.
  • update(object)
    In this method, the KieSession looks up the fact handle, via an identity check, for the passed object. Although, if property change listeners are provided to the JavaBeans that are inserted into the engine, it is possible to avoid the need to call update() method when the object changes.
  • insert(new <method name>())
    This method places a new object into the working memory.
  • retract(handle)
    This method removes an object from working memory. It is mapped to the delete method in a KieSession.
  • insertLogical(new <method name>())
    This method is similar to insert, but the object is automatically retracted from the working memory when there are no more facts to support the truth of the currently firing rule.
  • halt()
    This method terminates rule execution immediately. This is required for returning control to the point where the current session is put to work with fireUntilHalt() method.
  • getKieRuntime()
    The full KIE API is exposed through a predefined variable, kcontext, of type RuleContext. Its method getKieRuntime() delivers an object of type KieRuntime, which in turn provides access to a wealth of methods, many of which are useful for coding the rule logic. The call kcontext.getKieRuntime().halt() terminates rule execution immediately.