jess
Class Rete

java.lang.Object
  |
  +--jess.Rete

All Implemented Interfaces:

java.io.Serializable

public class Rete

extends java.lang.Object

implements java.io.Serializable

The reasoning engine. Executes the built Rete network, and coordinates many other activities.

(C) 1997 Ernest J. Friedman-Hill and Sandia National Laboratories

Author:

Ernest J. Friedman-Hill

See Also:

Serialized Form

Field Summary

static int	ACTIVATE
static int	EVERY_TIME
static int	INSTALL

Constructor Summary

Rete()

Rete(java.applet.Applet a)

Method Summary

protected void	aboutToFire(Activation a)
Deffacts	addDeffacts(Deffacts df) Creates a new deffacts in this object
Defglobal	addDefglobal(Defglobal dg) Creates a new Defglobal in this object.
void	addDefmodule(java.lang.String moduleName) Define a new module, which becomes current.
void	addDefmodule(java.lang.String moduleName, java.lang.String doccomment) Define a new module, which becomes current.
HasLHS	addDefrule(HasLHS dr) Creates a new defrule or defquery in this object
Deftemplate	addDeftemplate(Deftemplate dt) Creates a new deftemplate in this object.
void	addInputRouter(java.lang.String s, java.io.Reader is, boolean consoleLike)
void	addJessListener(JessListener jel)
void	addOutputRouter(java.lang.String s, java.io.Writer os)
Userfunction	addUserfunction(Userfunction uf) Creates a new function in this object Will happily destroy an old one.
Userpackage	addUserpackage(Userpackage up) Add a Userpackage to this engine.
Fact	assert(Fact f) Deprecated. Use assertFact instead.
Fact	assert(Fact f, Context c) Deprecated. Use assertFact instead
Fact	assertFact(Fact f) Assert a fact
Fact	assertFact(Fact f, Context c) Assert a fact
Fact	assertString(java.lang.String s, Context c) Assert a fact, as a String
void	bload(java.io.InputStream is) Read this object's state from the given stream.
void	bsave(java.io.OutputStream os) Save this object's state out to the given stream.
void	clear() Reinitialize engine Thanks to Karl Mueller for idea
void	clearFocusStack() Empty the focus stack.
void	clearStorage() Clear the storage used by store() and fetch().
Value	defclass(java.lang.String jessName, java.lang.String clazz, java.lang.String parent) Add a defclass definition to this engine
Value	definstance(java.lang.String jessTypename, java.lang.Object object, boolean dynamic, Context context) Tell this engine to pattern match on the given object.
int	doPreAssertionProcessing(Fact f)
Value	executeCommand(java.lang.String cmd) Call a Jess function in this engine's global context.
Value	fetch(java.lang.String name) Retrieve an object previously stored with store().
Deffacts	findDeffacts(java.lang.String name) Return the named deffacts object
Defglobal	findDefglobal(java.lang.String name)
HasLHS	findDefrule(java.lang.String name) Find a defrule object with a certain name
Deftemplate	findDeftemplate(java.lang.String name) Find a deftemplate object with a certain name
Fact	findFactByFact(Fact f) This find is fast, and can be used to find out quickly if a given fact is on the fact-list and if so, obtain a reference to it.
Fact	findFactByID(int id) This "find" is very slow; don't use it unless you have to.
Userfunction	findUserfunction(java.lang.String name) Find a userfunction, if there is one.
java.lang.Object	getActivationSemaphore() The monitor of the object returned from this method will be signalled whenever an activation appears.
java.applet.Applet	getApplet() Returns the applet this Rete is installed in.
java.lang.String	getCurrentModule() Return the name of the current module.
java.io.PrintWriter	getErrStream()
int	getEvalSalience() Fetch the salience evaluation behaviour
int	getEventMask()
static Factory	getFactory()
java.lang.String	getFocus() Query the focus module.
Context	getGlobalContext() Fetch the global execution context.
boolean	getInputMode(java.lang.String s)
java.io.Reader	getInputRouter(java.lang.String s)
java.io.Writer	getOutputRouter(java.lang.String s)
java.io.PrintWriter	getOutStream()
boolean	getResetGlobals() When resetGlobals is true, the initializers of global variables are evaluated when (reset) is executed.
void	halt() Stop the engine from firing rules.
protected void	justFired(Activation a)
java.util.Iterator	listActivations() Return an Iterator over all the activiations for the current module.
java.util.Iterator	listActivations(java.lang.String moduleName) Return an Iterator over all the activiations for the named module.
java.util.Iterator	listDeffacts() Return an Iterator over all the deffacts in this engine.
java.util.Iterator	listDefglobals() Return an Iterator over all the defglobals in this engine.
java.util.Iterator	listDefinstances() Return an Iterator over all the definstanced objects
java.util.Iterator	listDefrules() Return an Iterator over all the defrules in this engine.
java.util.Iterator	listDeftemplates() Return an Iterator over all the deftemplates in this engine, both explicit and implied.
java.util.Iterator	listFacts() Return an Iterator over all the facts currently on the fact-list
java.util.Iterator	listFocusStack() Iterate over the focus stack, from bottom to top.
java.util.Iterator	listFunctions() Return an Iterator over all the functions in this engine: built-in, user, and deffunctions.
java.util.Iterator	listJessListeners()
java.util.Iterator	listModules() List all modules
java.lang.String	popFocus() Remove the top module from the focus stack, and return it.
void	ppFacts(java.lang.String head, java.io.Writer output) Write the pretty print forms of the facts with the given head to the writer
void	ppFacts(java.io.Writer output) Write the pretty print forms of all facts to the writer
void	removeInputRouter(java.lang.String s)
void	removeJessListener(JessListener jel)
void	removeOutputRouter(java.lang.String s)
void	reset() Reset the Rete engine.
java.lang.String	resolveName(java.lang.String name) Decorate the name with the current module name, if it doesn't already contain a module name.
Fact	retract(Fact f) Retract a fact.
Fact	retractString(java.lang.String s) Karl Mueller NASA/GSFC Code 522.2 (Karl.R.Mueller@gsfc.nasa.gov) 27.January.1998 Retract a fact as a string
int	run() Run the actual engine.
int	run(int max) Run the rule engine.
java.util.Iterator	runQuery(java.lang.String name, ValueVector params) Quick way to run a defquery
int	runUntilHalt() Run until halt() is called.
void	setApplet(java.applet.Applet a) Associates this Rete with an applet so that, for instance, the (batch) commands will look for scripts using the applet's document base URL.
java.lang.String	setCurrentModule(java.lang.String name) Change the current module.
void	setEvalSalience(int method) Set the salience evaluation behaviour.
void	setEventMask(int i)
static void	setFactory(Factory f)
void	setFocus(java.lang.String name) Change the focus module.
void	setPendingFact(Fact fact, boolean assrt)
void	setResetGlobals(boolean reset) When resetGlobals is true, the initializers of global variables are evaluated when (reset) is executed.
java.lang.String	setStrategy(Strategy s)
Value	store(java.lang.String name, java.lang.Object val) Store a value in the engine under a given name for later retrieval by fetch.
Value	store(java.lang.String name, Value val) Store a value in the engine under a given name for later retrieval by fetch.
Value	undefinstance(java.lang.Object object) Tell this engine to stop pattern matching on the given object
Value	unDefrule(java.lang.String name)
void	verifyModule(java.lang.String moduleName) Throw an exception if the argument isn't the name of a module.
void	waitForActivations() Waits on the activation lock until a rule is activated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INSTALL

public static final int INSTALL

ACTIVATE

public static final int ACTIVATE

EVERY_TIME

public static final int EVERY_TIME

Constructor Detail

Rete

public Rete()

Rete

public Rete(java.applet.Applet a)

Parameters:

a - If this Rete object is being created inside an applet, pass it as an argument.

Method Detail

addInputRouter

public void addInputRouter(java.lang.String s,
                           java.io.Reader is,
                           boolean consoleLike)

Parameters:

s - The router name

is - A Reader where the router's data comes from

consoleLike - See the Jess manual

removeInputRouter

public void removeInputRouter(java.lang.String s)

Parameters:

s - The name of the router

getInputRouter

public java.io.Reader getInputRouter(java.lang.String s)

Parameters:

s - The router name

Returns:

The router, or null if none

addOutputRouter

public void addOutputRouter(java.lang.String s,
                            java.io.Writer os)

Parameters:

s - The router name

os - Where the data should go

removeOutputRouter

public void removeOutputRouter(java.lang.String s)

Parameters:

s - The name of the router

getInputMode

public boolean getInputMode(java.lang.String s)

Parameters:

s - The router name

Returns:

The console-like property for that router

getOutputRouter

public java.io.Writer getOutputRouter(java.lang.String s)

Parameters:

s - The router name

Returns:

The router, or null if none

getErrStream

public java.io.PrintWriter getErrStream()

Returns:

The WSTDERR router

getOutStream

public java.io.PrintWriter getOutStream()

Returns:

The WSTDOUT router

doPreAssertionProcessing

public int doPreAssertionProcessing(Fact f)
                             throws JessException

clear

public void clear()
           throws JessException

Reinitialize engine Thanks to Karl Mueller for idea

Throws:

JessException -

setPendingFact

public void setPendingFact(Fact fact,
                           boolean assrt)

reset

public void reset()
           throws JessException

Reset the Rete engine. Remove all facts, activations, etc. Clear all non-globals from the global scope. Assert (initial-fact). Broadcasts a JessEvent of type RESET.

Throws:

JessException - If anything goes wrong.

assertString

public Fact assertString(java.lang.String s,
                         Context c)
                  throws JessException

Assert a fact, as a String

Parameters:

s - A String representing a fact

Returns:

The fact that was asserted

Throws:

JessException - If something goes wrong

assert

public Fact assert(Fact f)
            throws JessException

Deprecated. Use assertFact instead.

assertFact

public Fact assertFact(Fact f)
                throws JessException

Assert a fact

Parameters:

f - A Fact object. This fact becomes the property of Jess after calling assertFact() -- don't change any of its fields until the fact is retracted!

Returns:

The fact ID on success, or -1.

Throws:

JessException - If anything goes wrong

assert

public Fact assert(Fact f,
                   Context c)
            throws JessException

Deprecated. Use assertFact instead

assertFact

public Fact assertFact(Fact f,
                       Context c)
                throws JessException

Assert a fact

Parameters:

f - A Fact object. This fact becomes the property of Jess after calling assertFact() -- don't change any of its fields until the fact is retracted!

Returns:

The fact ID on success, or -1.

Throws:

JessException - If anything goes wrong

retractString

public Fact retractString(java.lang.String s)
                   throws JessException

Karl Mueller NASA/GSFC Code 522.2 (Karl.R.Mueller@gsfc.nasa.gov) 27.January.1998 Retract a fact as a string

Parameters:

s -

Throws:

JessException -

retract

public Fact retract(Fact f)
             throws JessException

Retract a fact.

Parameters:

f - A Fact object. Doesn't need to be the actual object that appears on the fact-list; can just be a Fact that could compare equal to one.

Throws:

JessException - If anything goes wrong.

findFactByID

public Fact findFactByID(int id)
                  throws JessException

This "find" is very slow; don't use it unless you have to. Consider the returned Fact to be READ-ONLY!

Parameters:

id - The fact-id

Returns:

The fact, or null if none

Throws:

JessException - If something goes wrong

findFactByFact

public Fact findFactByFact(Fact f)
                    throws JessException

This find is fast, and can be used to find out quickly if a given fact is on the fact-list and if so, obtain a reference to it. The argument doesn't have to be a fact on the fact list -- only a Fact object identical to one that is.

ppFacts

public void ppFacts(java.lang.String head,
                    java.io.Writer output)
             throws java.io.IOException

Write the pretty print forms of the facts with the given head to the writer

ppFacts

public void ppFacts(java.io.Writer output)
             throws java.io.IOException

Write the pretty print forms of all facts to the writer

Returns:

Throws:

JessException -

listDeffacts

public java.util.Iterator listDeffacts()

Return an Iterator over all the deffacts in this engine.

findDeffacts

public Deffacts findDeffacts(java.lang.String name)

Return the named deffacts object

listDeftemplates

public java.util.Iterator listDeftemplates()

Return an Iterator over all the deftemplates in this engine, both explicit and implied.

listDefrules

public java.util.Iterator listDefrules()

Return an Iterator over all the defrules in this engine.

listFacts

public java.util.Iterator listFacts()

Return an Iterator over all the facts currently on the fact-list

listDefinstances

public java.util.Iterator listDefinstances()

Return an Iterator over all the definstanced objects

listDefglobals

public java.util.Iterator listDefglobals()

Return an Iterator over all the defglobals in this engine.

listFunctions

public java.util.Iterator listFunctions()

Return an Iterator over all the functions in this engine: built-in, user, and deffunctions.

findDefrule

public final HasLHS findDefrule(java.lang.String name)

Find a defrule object with a certain name

Parameters:

name -

Returns:

findDeftemplate

public Deftemplate findDeftemplate(java.lang.String name)
                            throws JessException

Find a deftemplate object with a certain name

Parameters:

name -

Returns:

addDeftemplate

public Deftemplate addDeftemplate(Deftemplate dt)
                           throws JessException

Creates a new deftemplate in this object. Ensure that every deftemplate has a unique class name.

Parameters:

dt -

Returns:

The argument.

Throws:

JessException - If the deftemplate is already defined

addDeffacts

public Deffacts addDeffacts(Deffacts df)
                     throws JessException

Creates a new deffacts in this object

Parameters:

df -

Returns:

Throws:

JessException -

addDefglobal

public Defglobal addDefglobal(Defglobal dg)
                       throws JessException

Creates a new Defglobal in this object. Trick it into resetting right now, regardless of the setting of resetGlobals.

Parameters:

dg -

Returns:

Throws:

JessException -

findDefglobal

public Defglobal findDefglobal(java.lang.String name)

Parameters:

name -

Returns:

addUserfunction

public Userfunction addUserfunction(Userfunction uf)

Creates a new function in this object Will happily destroy an old one.

Parameters:

uf - A new USerfunction

Returns:

The parameter, or null if call rejected by event handler

addUserpackage

public Userpackage addUserpackage(Userpackage up)

Add a Userpackage to this engine. A package generally calls addUserfunction lots of times.

Parameters:

up - The package object

Returns:

The package object, or null if call rejected by event handler

findUserfunction

public final Userfunction findUserfunction(java.lang.String name)

Find a userfunction, if there is one.

Parameters:

name - The name of the function

Returns:

The Userfunction object, if there is one.

addDefrule

public final HasLHS addDefrule(HasLHS dr)
                        throws JessException

Creates a new defrule or defquery in this object

Parameters:

dr - A Defrule or Defquery

Returns:

The added object

Throws:

JessException - If anything goes wrong.

unDefrule

public final Value unDefrule(java.lang.String name)
                      throws JessException

Parameters:

name -

Returns:

Throws:

JessException -

addDefmodule

public void addDefmodule(java.lang.String moduleName)
                  throws JessException

Define a new module, which becomes current.

addDefmodule

public void addDefmodule(java.lang.String moduleName,
                         java.lang.String doccomment)
                  throws JessException

Define a new module, which becomes current.

getCurrentModule

public java.lang.String getCurrentModule()

Return the name of the current module.

setCurrentModule

public java.lang.String setCurrentModule(java.lang.String name)
                                  throws JessException

Change the current module.

listModules

public java.util.Iterator listModules()
                               throws JessException

List all modules

getFocus

public java.lang.String getFocus()
                          throws JessException

Query the focus module.

setFocus

public void setFocus(java.lang.String name)
              throws JessException

Change the focus module.

listFocusStack

public java.util.Iterator listFocusStack()
                                  throws JessException

Iterate over the focus stack, from bottom to top. The current focus module is returned last.

clearFocusStack

public void clearFocusStack()

Empty the focus stack.

popFocus

public java.lang.String popFocus()
                          throws JessException

Remove the top module from the focus stack, and return it.

verifyModule

public void verifyModule(java.lang.String moduleName)
                  throws JessException

Throw an exception if the argument isn't the name of a module.

resolveName

public java.lang.String resolveName(java.lang.String name)

Decorate the name with the current module name, if it doesn't already contain a module name.

listActivations

public java.util.Iterator listActivations()

Return an Iterator over all the activiations for the current module. Note that some of the activations may be cancelled or already fired; check the return value of "isInactive()"for each one to be sure.

listActivations

public java.util.Iterator listActivations(java.lang.String moduleName)
                                   throws JessException

Return an Iterator over all the activiations for the named module. "*" is not accepted. Note that some of the activations may be cancelled or already fired; check the return value of "isInactive()"for each one to be sure.

getActivationSemaphore

public java.lang.Object getActivationSemaphore()

The monitor of the object returned from this method will be signalled whenever an activation appears. Thus a run-loop could wait on this monitor when idle.

waitForActivations

public void waitForActivations()

Waits on the activation lock until a rule is activated. Can be called in a run-loop to wait for more rules to fire.

See Also:

getActivationSemaphore

setStrategy

public java.lang.String setStrategy(Strategy s)
                             throws JessException

Parameters:

s -

Returns:

Throws:

JessException -

setEvalSalience

public final void setEvalSalience(int method)
                           throws JessException

Set the salience evaluation behaviour. The behaviour can be one of INSTALL, ACTIVATE, or EVERY_TIME; the default is INSTALL. When the behaviour is INSTALL, a rule's salience is evulated once when the rule is compiled. If it is ACTIVATE, it is computed each time the rule is activated. If it is EVERY_TIME, salience evaluations are done for all rules each time the next rule on the agenda is to be chosen.

Parameters:

method - One of the acceptable values

Throws:

JessException - If something goes wrong

getEvalSalience

public final int getEvalSalience()

Fetch the salience evaluation behaviour

Returns:

The salience evaluation behaviour

run

public int run()
        throws JessException

Run the actual engine.

Returns:

The number of rules fired

Throws:

JessException - If anything goes wrong.

aboutToFire

protected void aboutToFire(Activation a)

justFired

protected void justFired(Activation a)

run

public int run(int max)
        throws JessException

Run the rule engine.

Parameters:

max - The maximum number of rules to fire

Returns:

The number of rules that fired

Throws:

JessException - If anything goes wrong.

runUntilHalt

public int runUntilHalt()
                 throws JessException

Run until halt() is called. When no rules are active, the calling Thread will be waiting on the activation semaphore.

halt

public void halt()
          throws JessException

Stop the engine from firing rules.

addJessListener

public void addJessListener(JessListener jel)

removeJessListener

public void removeJessListener(JessListener jel)

listJessListeners

public java.util.Iterator listJessListeners()

getEventMask

public int getEventMask()

setEventMask

public void setEventMask(int i)

bload

public void bload(java.io.InputStream is)
           throws java.io.IOException,
                  java.lang.ClassNotFoundException

Read this object's state from the given stream.

bsave

public void bsave(java.io.OutputStream os)
           throws java.io.IOException

Save this object's state out to the given stream.

definstance

public Value definstance(java.lang.String jessTypename,
                         java.lang.Object object,
                         boolean dynamic,
                         Context context)
                  throws JessException

Tell this engine to pattern match on the given object.

Parameters:

jessTypename - The name of a defclass

object - An object of the defclass's type

dynamic - true if PropertyChangeListeners should be used

undefinstance

public Value undefinstance(java.lang.Object object)
                    throws JessException

Tell this engine to stop pattern matching on the given object

Parameters:

object - An object of the defclass's type

defclass

public Value defclass(java.lang.String jessName,
                      java.lang.String clazz,
                      java.lang.String parent)
               throws JessException

Add a defclass definition to this engine

Parameters:

jessName - The name Jess should use for this defclass

clazz - The name of the Java class

parent - If non-null, a parent deftemplate or defclass name

getApplet

public java.applet.Applet getApplet()

Returns the applet this Rete is installed in. Returns null if none.

Returns:

The applet

setApplet

public void setApplet(java.applet.Applet a)

Associates this Rete with an applet so that, for instance, the (batch) commands will look for scripts using the applet's document base URL.

Parameters:

a - The applet

getGlobalContext

public final Context getGlobalContext()

Fetch the global execution context.

Returns:

The global execution context.

executeCommand

public Value executeCommand(java.lang.String cmd)
                     throws JessException

Call a Jess function in this engine's global context.

Parameters:

cmd - A string containing a value Jess function

Returns:

The function's result.

Throws:

JessException - If anything goes wrong

setResetGlobals

public final void setResetGlobals(boolean reset)

When resetGlobals is true, the initializers of global variables are evaluated when (reset) is executed.

Parameters:

reset - The value of this property

getResetGlobals

public final boolean getResetGlobals()

When resetGlobals is true, the initializers of global variables are evaluated when (reset) is executed.

Returns:

The value of this property

store

public Value store(java.lang.String name,
                   Value val)

Store a value in the engine under a given name for later retrieval by fetch.

Parameters:

name - A key under which to file the value

val - The value to store

Returns:

Any old value stored under this name, or null.

See Also:

fetch(java.lang.String)

store

public Value store(java.lang.String name,
                   java.lang.Object val)

Store a value in the engine under a given name for later retrieval by fetch. The Object is first wrapped in a new jess.Value object.

Parameters:

name - A key under which to file the value

val - The value to store

Returns:

Any old value stored under this name, or null.

fetch

public Value fetch(java.lang.String name)

Retrieve an object previously stored with store().

Parameters:

name - The key under which to find an object

Returns:

The object, or null if not found.

See Also:

store(java.lang.String, jess.Value)

clearStorage

public void clearStorage()

Clear the storage used by store() and fetch().

getFactory

public static Factory getFactory()

setFactory

public static void setFactory(Factory f)

runQuery

public java.util.Iterator runQuery(java.lang.String name,
                                   ValueVector params)
                            throws JessException

Quick way to run a defquery