jess
Interface JessListener

All Superinterfaces:

java.util.EventListener

All Known Implementing Classes:

DebugListener, JessEventAdapter, PrintingListener, Rete

public interface JessListener

extends java.util.EventListener

JessListener is a notification interface for Jess events. Objects that wish to be notified of significant happenings in a Jess engine should implement this interface, then register themselves with a Rete object using Rete.addJessListener(jess.JessListener). Rete (potentially) fires events at all critical junctures during its execution: when rules fire, when a Rete.reset() or Rete.clear() call is made, when a fact is asserted or retracted, etc. JessEvent has a JessEvent.getType() method to tell you what sort of event you have been notified of; the type will be one of the constants in the JessEvent class.

As an example, let's suppose you'd like your program's graphical interface to display a running count of the number of facts on the fact-list, and the name of the last executed rule. You've provided a static method, MyGUI.displayCurrentRule(String ruleName), which you would like to have called when a rule fires. You've got a pair of methods MyGUI.incrementFactCount() and MyGUI.decrementFactCount() to keep track of facts. And you've got one more static method, MyGUI.clearDisplay(), to call when Jess is cleared or reset. To accomplish this, you simply need to write an event handler, install it, and set the event mask properly. Your event handler class might look like this.

 import jess.*;

 public class ExMyEventHandler implements JessListener {
     public void eventHappened(JessEvent je) {
         int defaultMask = JessEvent.DEFRULE_FIRED | JessEvent.FACT | JessEvent.RESET;
         int type = je.getType();
         switch (type) {
              case JessEvent.RESET:
               MyGUI.clearDisplay();
               break;

             case JessEvent.DEFRULE_FIRED:
               MyGUI.displayCurrentRule( ((Activation) je.getObject()).getRule().getName());
               break;

             case JessEvent.FACT | JessEvent.REMOVED:
               MyGUI.decrementFactCount();
               break;

             case JessEvent.FACT:
               MyGUI.incrementFactCount();
               break;

             default:
               // ignore
         }
     }
 }
 

Note how the event type constant for fact retracting is composed from FACT | REMOVED. In general, constants like DEFRULE, DEFTEMPLATE, etc, refer to the addition of a new construct, while composing these with REMOVE signifies the removal of the same construct.

To install this listener, you would simply create an instance and call jess.Rete.addEventListener(), then set the event mask:

 Rete engine = new Rete();
 engine.addJessListener(new ExMyEventHandler());
 engine.setEventMask(engine.getEventMask() | JessEvent.DEFRULE_FIRED | JessEvent.FACT | JessEvent.RESET );
 

When Rete.clear() is called, the event mask is typically reset to the default. When event handlers are called, they have the opportunity to alter the mask to re-install themselves. Alternatively, they can call Rete.removeJessListener(jess.JessListener) to unregister themselves.

Working with events from the Jess language

It's possible to work with the event classes from Jess language code as well. To write an event listener, you can use the JessEventAdapter class. This class works rather like the jess.awt adapter classes do. Usage is best illustrated with an example. Let's say you want to print a message each time a new template is defined, and you want to do it from Jess code. Here it is:

 (import jess.*)
 ;; Here is the event-handling deffunction
 ;; It accepts one argument, a JessEvent
 (deffunction display-deftemplate-from-event (?evt)
     (if (eq (JessEvent.DEFTEMPLATE) (get ?evt type)) then
     (printout t "New deftemplate: " (call (call ?evt getObject) getName) crlf)))

 ;; Here we install the above function using a JessEventAdapter
 (call (engine) addJessListener
     (new JessEventAdapter display-deftemplate-from-event (engine)))

 ;; Now we add DEFTEMPLATE to the event mask
 (set (engine) eventMask
 (bit-or (get (engine) eventMask) (JessEvent.DEFTEMPLATE)))
 

Now whenever a new template is defined, a message will be displayed.

(C) 2006 Sandia National Laboratories

See Also:

JessEvent, Rete.addJessListener(jess.JessListener), Rete.removeJessListener(jess.JessListener)

Method Summary

void	eventHappened(JessEvent je) Called by a JessEvent source when something interesting happens.

Method Detail

eventHappened

public void eventHappened(JessEvent je)
                   throws JessException

Called by a JessEvent source when something interesting happens. The typical implementation of eventHappened will switch on the return value of je.getType().

Parameters:

je - an event object describing the event.

Throws:

JessException - if any problem occurs during event handling.