jess
Class Rete

java.lang.Object
  extended by jess.Rete
All Implemented Interfaces:
java.io.Serializable, java.util.EventListener, JessListener

public class Rete
extends java.lang.Object
implements java.io.Serializable, JessListener

The central class in the Jess library. Executes the built Rete network, and coordinates many other activities. Rete is basically a facade for all the other classes in the Jess library.

The jess.Rete class is the rule engine itself. Each jess.Rete object has its own working memory, agenda, rules, etc. To embed Jess in a Java application, you'll simply need to create one or more jess.Rete objects and manipulate them appropriately.

(C) 2006 Sandia National Laboratories

See Also:
Serialized Form

Field Summary
static int ACTIVATE
          Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated whenever a rule is activated.
static int EVERY_TIME
          Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated before every rule is fired.
static int INSTALL
          Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated only when a rule is installed (the default.)
static java.lang.String LIBRARY_NAME
          The name of the script library file.
static java.lang.String LIBRARY_PATH_ID
          The name of a system property.
static java.util.Map s_lineNumberTable
           
 
Constructor Summary
Rete()
          Construct a single rule engine instance.
Rete(java.applet.Applet applet)
          Construct a single rule engine instance for use in an applet.
Rete(java.lang.Object appObject)
          Construct a Rete object and supply an example of an application class.
 
Method Summary
protected  void aboutToFire(Activation a)
          Allows a subclass to be notified immediately before a rule fires.
 Value add(java.lang.Object o)
          Add an object to working memory using various defaults.
 void addAll(java.util.Collection c)
          Add a collection of objects to working memory.
 void addAll(java.util.Iterator it)
          Add a collection of objects to working memory.
 void addDebugListener(JessListener jel)
          Add a listener so that it will receive debug events.
 Deffacts addDeffacts(Deffacts df)
          Add a deffacts construct to this rule engine.
 Defglobal addDefglobal(Defglobal dg)
          Creates a new Defglobal in this rule engine.
 java.util.List addDefglobals(java.util.List dg)
          Adds a list of Defglobals to this object, as if by addDefglobal().
 void addDefmodule(Defmodule module)
          Define a new module, which becomes current.
 void addDefmodule(java.lang.String name)
          Deprecated. As of Jess 7, use addDefmodule(Defmodule).
 void addDefmodule(java.lang.String name, java.lang.String comment)
          Deprecated. As of Jess 7, use addDefmodule(Defmodule).
 HasLHS addDefrule(HasLHS dr)
          Add a rule or query to this engine.
 Deftemplate addDeftemplate(Deftemplate dt)
          Creates a new deftemplate in this rule engine.
 void addInputRouter(java.lang.String s, java.io.Reader is, boolean consoleLike)
          Add an "input router" to this object.
 void addJessListener(JessListener jel)
          Register an event listener with this rule engine.
 void addOutputRouter(java.lang.String s, java.io.Writer os)
          Add an "output router" to this object.
 Userfunction addUserfunction(Userfunction uf)
          Creates a new function in this rule engine.
 Userpackage addUserpackage(Userpackage up)
          Add a Userpackage to this engine.
 Fact assertFact(Fact f)
          Assert a fact.
 Fact assertFact(Fact f, Context c)
          Assert a fact, using the given execution context.
 Fact assertString(java.lang.String s)
          Assert a fact, as a String, using the global execution context.
 Fact assertString(java.lang.String s, Context c)
          Assert a fact, as a String.
 Value batch(java.lang.String filename)
          Execute a file of Jess language code or JessML code.
 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()
          Reinitializes this rule engine.
 void clearFocusStack()
          Empty the module focus stack.
 void clearStorage()
          Clear the storage used by store() and fetch().
 boolean containsObject(java.lang.Object o)
          Indicates whether a given object is being held in working memory.
 int countQueryResults(java.lang.String name, ValueVector params)
          Invoke the named query and return the count of matching results.
 int countQueryResults(java.lang.String name, ValueVector params, Context context)
          Invoke the named query and return the count of matching results.
 Deftemplate createDeftemplate(java.lang.String name)
          Find or create the deftemplate by the given name.
 Rete createPeer()
          Return a new Rete object that is a "peer" of this one.
 Value defclass(java.lang.String jessName, java.lang.String clazz, java.lang.String parent)
          Add a defclass definition (a deftemplate) to this engine.
 Value defclass(java.lang.String jessName, java.lang.String clazz, java.lang.String parent, boolean includeMemberVariables)
          Add a defclass definition (a deftemplate) to this engine.
 void defineFeature(java.lang.String name)
          Register a named feature, as if by the "provide" function.
 Value definstance(java.lang.String jessTypename, java.lang.Object object, boolean dynamic)
          Make a shadow fact for the given object and add it to working memory.
 Value definstance(java.lang.String jessTypename, java.lang.Object object, boolean dynamic, Context context)
          Make a shadow fact for the given object and add it to working memory.
protected  int doPreAssertionProcessing(Fact f)
          This method is called as a Fact is about to be asserted.
 Value eval(java.lang.String cmd)
          Evaluate a Jess expression in this engine's global context.
 Value eval(java.lang.String cmd, Context context)
          Evaluate a Jess expression in the given execution context.
 void eventHappened(JessEvent je)
          Responds to a JessEvent by emitting "watch" messages.
 Value executeCommand(java.lang.String cmd)
          Deprecated. Use eval() instead.
 Value executeCommand(java.lang.String cmd, Context context)
          Deprecated. Use eval() instead.
 Value fetch(java.lang.String name)
          Retrieve an object previously stored with store().
 java.lang.Class findClass(java.lang.String className)
          Load a class using the active ClassLoader.
 Deffacts findDeffacts(java.lang.String name)
          Return the named deffacts object.
 Defglobal findDefglobal(java.lang.String name)
          Look up a defglobal by name.
 HasLHS findDefrule(java.lang.String name)
          Find a defrule or defquery object with a certain name.
 Deftemplate findDeftemplate(java.lang.String name)
          Find a deftemplate object with a certain name.
 Fact findFactByFact(Fact f)
          Find a Fact object in working memory, given a Fact object that is identical to it.
 Fact findFactByID(int id)
          Return a Fact object given its numeric fact-id.
 Defmodule findModule(java.lang.String name)
          Return the Defmodule object corresponding to the Jess module with the given name.
 Userfunction findUserfunction(java.lang.String name)
          Find a userfunction, if there is one by the given name.
 java.lang.Object getActivationSemaphore()
          The monitor of the object returned from this method will be signalled whenever an activation appears.
 java.applet.Applet getApplet()
          If this Rete object is part of an applet, and the applet was supplied as a constructor argument, then this method will return it.
 java.lang.Class getAppObjectClass()
          Return the Class that represents the "app object" for this Rete.
 java.lang.ClassLoader getClassLoader()
          Return the ClassLoader that will be used to find classes named in Jess ocde.
 ClassResearcher getClassResearcher()
          Return the ClassResearcher this engine will use to learn about Java classes mentioned in Jess code.
 java.lang.String getCurrentModule()
          Return the name of the current module.
 java.io.PrintWriter getErrStream()
          Return the WSTDERR router, where Jess sends error messages.
 int getEvalSalience()
          Fetch the salience evaluation behaviour, which helps determine the priority of rule firing.
 int getEventMask()
          Query the current value of the event mask.
static Factory getFactory()
          Return the Factory Jess will use to create Rete Tokens.
 java.lang.String getFocus()
          Query the focus module.
 Context getGlobalContext()
          Fetch the global execution context.
 boolean getInputMode(java.lang.String s)
          Returns the consoleLike property for the named input router.
 java.io.Reader getInputRouter(java.lang.String s)
          Return the Reader registered under a given router name.
 char getMemberChar()
          The character used to denote memberhood in "Java patterns." Normally a period, but can be changed to allow dots in slot names (for example.)
 java.util.Iterator getObjects(Filter filter)
          Return a subset of Java objects (definstances) in working memory.
 java.io.Writer getOutputRouter(java.lang.String s)
          Return the Writer registered under a given router name.
 java.io.PrintWriter getOutStream()
          Return the WSTDOUT router, where Jess sends much of its standard output.
 boolean getResetGlobals()
          Return the resetGlobals property.
 java.net.URL getResource(java.lang.String name)
          Load a resource using the current ClassLoader's getResource() method.
 java.lang.Thread getRunThread()
          If this engine is currently firing a rule, returns the Thread that the rule is firing on; otherwise, returns null.
 Fact getShadowFactForObject(java.lang.Object o)
          Returns the "shadow fact" that represents the given object in working memory.
 Strategy getStrategy()
          Retrieve the Strategy object this engine is using to order activations on the agenda.
 java.util.List getSupportedFacts(Fact supporter)
          Returns a list of Fact objects that receive logical support from the argument.
 java.util.List getSupportingTokens(Fact fact)
          Returns a list of one or more jess.Token objects that provide logical support for this fact.
 Activation getThisActivation()
          Get the activation record for the currently firing rule.
 java.lang.String getThisRuleName()
          Find out the name of the currently firing rule.
 ValueFactory getValueFactory()
          Fetch the value factory for this engine.
 void halt()
          Stop the engine from firing rules.
 boolean hasActivations()
          Check whether the current module includes any activations to fire.
 boolean hasActivations(java.lang.String moduleName)
          Check whether there are any activations to fire in the named module.
 void importClass(java.lang.String clazz)
          Make a single class name available for use in unqualified form in Jess code.
 void importPackage(java.lang.String pack)
          Make all the classes in a package available for use in unqualified form from Jess code.
 boolean isDebug()
          Return whether the engine is in debug mode.
 boolean isFeatureDefined(java.lang.String name)
          Return whether a feature name has been registered by the "provide" function.
 boolean isHalted()
          Returns true if halt has been called since the last run() call.
 java.lang.Class javaClassForDefclass(java.lang.String name)
          Return the Java Class corresponding to a given Defclass name, or null if the name was not found.
protected  void justFired(Activation a)
          Allows a subclass to be notified immediately after a rule fires.
 java.util.Iterator listActivations()
          Return an Iterator over all the activations for the current module.
 java.util.Iterator listActivations(java.lang.String moduleName)
          Return an Iterator over all the activations for the named module.
 java.util.Iterator listDebugListeners()
          Return an iterator over all listeners that will receive debug events.
 java.util.Iterator listDefclasses()
          Return an Iterator over all the names of all defclasses.
 java.util.Iterator listDeffacts()
          Return an Iterator over all the deffacts in this engine.
 java.util.Iterator listDeffunctions()
          Return an Iterator over all deffunctions defined in this engine, including the ones defined in the script library.
 java.util.Iterator listDefglobals()
          Return an Iterator over all the defglobals in this engine.
 java.util.Iterator listDefinstances()
          Return an Iterator over all the Java objects currently represented by shadow facts in working memory.
 java.util.Iterator listDefrules()
          Return an Iterator over all the rules and queries defined 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 in working memory.
 java.util.Iterator listFocusStack()
          Iterate over the module focus stack, from bottom to top.
 java.util.Iterator listFunctions()
          Return an Iterator over all special functions defined in this engine, including user-defined Java functions, deffunctions, functions defined in the Jess script library, imported static functions, but not including the built-in (intrinsic) functions.
 java.util.Iterator listJessListeners()
          Returns an iterator over all previously registered event listeners.
 java.util.Iterator listModules()
          List all modules.
static LineNumberRecord lookupFunction(Funcall fc)
          Return information about the source location of a given function call, if known.
 WorkingMemoryMarker mark()
          Return a marker for the current state of working memory.
 Fact modify(Fact fact, java.lang.String[] slotNames, Value[] slotValues)
          Modify any number of slots in a fact.
 Fact modify(Fact fact, java.lang.String[] slotNames, Value[] slotValues, Context context)
          Modify any number of slots in a fact.
 Fact modify(Fact fact, java.lang.String slotName, Value slotValue)
          Modify one slot in a fact.
 Fact modify(Fact fact, java.lang.String slotName, Value slotValue, Context context)
          Modify one slot in a fact.
 Activation peekNextActivation()
          Return the next activation record from the agenda.
 java.lang.String popFocus(java.lang.String expected)
          Remove the top module from the focus stack, and return it.
 void ppFacts(java.lang.String head, java.io.Writer output)
          Pretty-print all the facts with the given head to the Writer.
 void ppFacts(java.lang.String head, java.io.Writer output, boolean inXML)
          Pretty-print all the facts with the given head to the Writer.
 void ppFacts(java.io.Writer output)
          Pretty-print all the facts in working memory to the Writer.
 void ppFacts(java.io.Writer output, boolean inXML)
          Pretty-print all the facts in working memory to the Writer.
static void recordFunction(Funcall fc, LineNumberRecord lnr)
          Store a debug symbol for a function call.
static void recordFunction(Funcall fc, java.lang.String fileName, int lineno)
          Store a debug symbol for a function call.
 Fact remove(java.lang.Object object)
          Remove the given object from working memory.
 void removeAll(java.util.Collection c)
          Remove a collection of objects from working memory.
 void removeDebugListener(JessListener jel)
          Remove a listener so that it will no longer receive debug events.
 void removeDeffacts(java.lang.String name)
          Remove a deffacts construct from this engine and any peers.
 void removeDefglobal(java.lang.String name)
          Removes the given defglobal from this engine.
 void removeDefmodule(java.lang.String name)
          Remove the given defmodule from this engine and all peered engines.
 void removeDefrule(java.lang.String name)
          Remove a rule or query from this Rete object.
 void removeDeftemplate(java.lang.String name)
          Removes an unused deftemplate from this engine, and from all peered engines.
 void removeFacts(java.lang.String name)
          Retract all the facts using a given template that are currently in working memory.
 void removeInputRouter(java.lang.String s)
          Remove the named router from the engine.
 void removeJessListener(JessListener jel)
          Remove an event listener from this rule engine.
 void removeOutputRouter(java.lang.String s)
          Remove the named router from the engine.
 void removeUserDefinedFunctions()
          Removes all user-defined functions from this engine.
 void removeUserfunction(java.lang.String name)
          Remove any currently defined function by the given name.
 void reset()
          Reset the rule engine.
 void resetToMark(WorkingMemoryMarker marker)
          Restore working memory by retracting all facts asserted after the given marker was placed.
 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)
          Retract a fact represented as a string.
 int run()
          Run the rule engine.
 int run(int max)
          Run the rule engine.
 java.util.Iterator runQuery(java.lang.String name, ValueVector params)
          Deprecated. Since Jess 7.0, superceded by runQueryStar()
 java.util.Iterator runQuery(java.lang.String name, ValueVector params, Context context)
          Deprecated. Since Jess 7.0, superceded by runQueryStar()
 QueryResult runQueryStar(java.lang.String name, ValueVector params)
          Invoke the named query and return the results.
 QueryResult runQueryStar(java.lang.String name, ValueVector params, Context context)
          Invoke the named query and return the results.
 int runUntilHalt()
          Run the rule engine until halt() is called.
 void setApplet(java.applet.Applet applet)
          Notify this Rete object that it is part of an Applet.
 void setAppObject(java.lang.Object appObject)
          Specify the "app object" for this Rete.
 void setClassLoader(java.lang.ClassLoader loader)
          Specify the ClassLoader that will be used to load classes named in Jess code.
 void setClassResearcher(ClassResearcher researcher)
          Set the ClassResearcher this engine will use to learn about Java classes mentioned in Jess code.
 java.lang.String setCurrentModule(java.lang.String name)
          Change the current module.
 void setDebug(boolean debug)
          Specify whether the engine should be in debug mode.
 void setDynamicChecking(boolean doCheck)
          Turns dynamic constraint checking on or off.
 void setEvalSalience(int method)
          Set the salience evaluation behaviour.
 void setEventMask(int mask)
          You can control which events this object will fire using this method.
static void setFactory(Factory f)
          Set the Factory Jess will use to create Rete Tokens.
 void setFocus(java.lang.String name)
          Change the focus module.
 void setMemberChar(char c)
          Change the character that denotes a member in "Java patterns."
 void setPassiveMode(boolean passiveMode)
          Return whether the engine is in passive mode.
 void setResetGlobals(boolean reset)
          Set the resetGlobals property.
 java.lang.String setStrategy(Strategy s)
          Tell this engine to use the given Strategy object to order the rules on the agenda.
 void setValueFactory(ValueFactory factory)
          Set the value factory used by this engine.
 java.lang.String setWatchRouter(java.lang.String s)
          Sets the router the "watch" facility will use for output.
 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.
 java.lang.String toString()
          Returns "[Rete]".
 Value unDeffacts(java.lang.String name)
          Remove a deffacts from the engine.
 Fact undefinstance(java.lang.Object object)
          Remove the given object from working memory.
 Value unDefrule(java.lang.String name)
          Deprecated. As of Jess 7.1, use removeDefrule(String)
 void unwatch(int which)
          Cancel some debugging information.
 void unwatchAll()
          Cancel all debugging info.
 Value updateObject(java.lang.Object object)
          Bring a shadow fact up to date.
 Value updateObject(java.lang.Object object, Context context)
           
 Value updateObject(java.lang.Object object, java.lang.String slotName)
          Bring one slot of a shadow fact up to date.
 void verifyModule(java.lang.String name)
          Throw an exception if the argument isn't the name of a module.
 void waitForActivations()
          Waits on the activation lock as long as the agenda is empty.
 void watch(int which)
          Produce some debugging information.
 void watchAll()
          Produce all possible debugging info.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

INSTALL

public static final int INSTALL
Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated only when a rule is installed (the default.)

See Also:
Constant Field Values

ACTIVATE

public static final int ACTIVATE
Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated whenever a rule is activated.

See Also:
Constant Field Values

EVERY_TIME

public static final int EVERY_TIME
Constant passed to setEvalSalience() to indicate that dynamic salience expressions should be evaluated before every rule is fired. This has a large impact on performance.

See Also:
Constant Field Values

LIBRARY_PATH_ID

public static final java.lang.String LIBRARY_PATH_ID
The name of a system property. If this property is defined, Jess will assume it names the directory from which the script library "scriptlib.clp" should be loaded.

See Also:
Constant Field Values

LIBRARY_NAME

public static final java.lang.String LIBRARY_NAME
The name of the script library file. Rete instances load this file when they are created.

See Also:
Constant Field Values

s_lineNumberTable

public static java.util.Map s_lineNumberTable
Constructor Detail

Rete

public Rete(java.lang.Object appObject)
Construct a Rete object and supply an example of an application class. Jess will try to find things (like files passed as arguments to "batch") "near" where this class was loaded; i.e., it will find them using the classloader used to load the argument.

If the system property "jess.library.path.id" exists, Jess assumes it names the directory in which the script library scriptlib.clp should be found. Otherwise, the script library will be loaded from the class path.

Parameters:
appObject - any object loaded by the application-level class loader
See Also:
LIBRARY_PATH_ID

Rete

public Rete()
Construct a single rule engine instance. It will use the context ClassLoader to load classes named in Jess code.

If the system property "jess.library.path.id" exists, Jess assumes it names the directory in which the script library scriptlib.clp should be found. Otherwise, the script library will be loaded from the class path.

See Also:
LIBRARY_PATH_ID

Rete

public Rete(java.applet.Applet applet)
Construct a single rule engine instance for use in an applet. It will use the applet's ClassLoader to load classes named in Jess code.

If the system property "jess.library.path.id" exists, Jess assumes it names the directory in which the script library scriptlib.clp should be found. Otherwise, the script library will be loaded from the class path.

Parameters:
applet - If this Rete object is being created inside an applet, pass it as an argument.
See Also:
LIBRARY_PATH_ID
Method Detail

createPeer

public Rete createPeer()

Return a new Rete object that is a "peer" of this one. The two Rete instances will share a single Rete network, rule base, defglobal list, function list, and class source, but will otherwise be independent; in particular, each has its own separate set of Rete memories. A rule added to any of a set of peered Rete instances will appear in the Rete network of all such instances.

Constructing a peered Rete object is a fast operation, and two peered Rete objects use a lot less memory than two independent ones loaded with the same rules. Therefore peering is a useful way to service multiple clients with the same set of rules, as in a Web application.

Returns:
a new Rete object connected to this one as a peer

addInputRouter

public void addInputRouter(java.lang.String s,
                           java.io.Reader is,
                           boolean consoleLike)
Add an "input router" to this object. An input router is basically just a Reader that Jess can read from. It's stored in a map and looked up by name. The router "t" corresponds to standard input, but you can define your own routers, or reassign existing ones, using this method.

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)
Remove the named router from the engine. The Reader is not closed -- if it needs to be closed, you must do that yourself.

Parameters:
s - the name of the router to remove

getInputRouter

public java.io.Reader getInputRouter(java.lang.String s)
Return the Reader registered under a given router name.

Parameters:
s - the router name
Returns:
the router, or null if none

addOutputRouter

public void addOutputRouter(java.lang.String s,
                            java.io.Writer os)
Add an "output router" to this object. An input router is basically just a Writer that Jess can send data to. It's stored in a map and looked up by name. The router "t" corresponds to standard output, but you can define your own routers, or reassign existing ones, using this method.

Parameters:
s - the router name
os - where the data should go

removeOutputRouter

public void removeOutputRouter(java.lang.String s)
Remove the named router from the engine. The Writer is not closed -- if it needs to be closed, you must do that yourself.

Parameters:
s - the name of the router

getInputMode

public boolean getInputMode(java.lang.String s)
Returns the consoleLike property for the named input router. The boolean argument consoleLike to the addInputRouter method specifies whether the stream should be treated like the standard input or like a file. The difference is that on console-like streams, a read call consumes an entire line of input, but only the first token is returned; while on file-like streams, only the characters that make up each token are consumed on any one call. That means, for instance, that a read followed by a readline will consume two lines of text from a console-like stream, but only one from a file-like stream, given that the first line is of non-zero length.

Parameters:
s - the router name
Returns:
the console-like property for that router, or null if the router doesn't exist.

getOutputRouter

public java.io.Writer getOutputRouter(java.lang.String s)
Return the Writer registered under a given router name. If you create a router using addOutputRouter(java.lang.String, java.io.Writer), the return value may be the Writer you passed to that method, but it may instead be a PrintWriter wrapping that Writer.

Parameters:
s - The router name
Returns:
The router, or null if none

getErrStream

public java.io.PrintWriter getErrStream()
Return the WSTDERR router, where Jess sends error messages.

Returns:
The WSTDERR router

getOutStream

public java.io.PrintWriter getOutStream()
Return the WSTDOUT router, where Jess sends much of its standard output. The "t" router is distinct from WSTDOUT, but they initially both go to System.out.

Returns:
The WSTDOUT router

doPreAssertionProcessing

protected int doPreAssertionProcessing(Fact f)
                                throws JessException
This method is called as a Fact is about to be asserted. It is meant to be overridden by extensions that need to do additional processig when facts are added to working memory.

Parameters:
f - a Fact about to be asserted
Returns:
non-zero if the assertion should not proceed
Throws:
JessException

clear

public void clear()
           throws JessException
Reinitializes this rule engine. Working memory is cleared, all rules are deleted, deffunctions are removed, all templates are forgotten, and a JessEvent of type JessEvent.CLEAR is sent. The watch state, event mask, and event handlers are unchanged.

Throws:
JessException - if anything goes wrong

reset

public void reset()
           throws JessException
Reset the rule engine. Clears working memory and the agenda, but rules remain defined. Clears all non-globals from the global scope. Asserts (initial-fact), reasserts all deffacts and definstances, then broadcasts a JessEvent of type JessEvent.RESET.

Throws:
JessException - if anything goes wrong

setDynamicChecking

public void setDynamicChecking(boolean doCheck)
Turns dynamic constraint checking on or off. When checking is on, slot constraints are checked before a fact is asserted. By default, this feature is turned off.

Parameters:
doCheck - true if this engine should do dynamic constraint checking

assertString

public Fact assertString(java.lang.String s,
                         Context c)
                  throws JessException
Assert a fact, as a String. For example, you can say

Rete engine = ...
Context context = ...
engine.assertString("(person (name Fred))", context);

Parameters:
s - a String representing a fact
c - an execution context for resolving variables
Returns:
the fact that was asserted
Throws:
JessException - if something goes wrong

assertString

public Fact assertString(java.lang.String s)
                  throws JessException
Assert a fact, as a String, using the global execution context. For example, you can say

Rete engine = ...
engine.assertString("(person (name Fred))");

Parameters:
s - a String representing a fact
Returns:
the fact that was asserted
Throws:
JessException - if something goes wrong

assertFact

public Fact assertFact(Fact f)
                throws JessException
Assert a fact. Adds the given Fact to working memory. This fact becomes the property of Jess after calling assertFact() -- don't change any of its fields until the fact is retracted! You're also not allowed to call this method on a Fact that already belongs to the working memory of another Rete instance. The behavior in either case is undefined, and generally bad.

Parameters:
f - a Fact object.
Returns:
the fact
Throws:
JessException - if anything goes wrong

assertFact

public Fact assertFact(Fact f,
                       Context c)
                throws JessException
Assert a fact, using the given execution context. Adds the given Fact to working memory. This fact becomes the property of Jess after calling assertFact() -- don't change any of its fields until the fact is retracted! You're also not allowed to call this method on a Fact that already belongs to the working memory of another Rete instance. The behavior in either case is undefined, and generally bad.

Parameters:
f - a Fact object.
c - an execution context
Returns:
the fact
Throws:
JessException - if anything goes wrong

retractString

public Fact retractString(java.lang.String s)
                   throws JessException
Retract a fact represented as a string. Parses the String to create a Fact object, then tries to remove that fact from working memory.

Parameters:
s - a String form of a Fact
Throws:
JessException

retract

public Fact retract(Fact f)
             throws JessException
Retract a fact. Removes the Fact from working memory. 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.

Parameters:
f - a Fact object
Throws:
JessException - if anything goes wrong

removeFacts

public void removeFacts(java.lang.String name)
                 throws JessException
Retract all the facts using a given template that are currently in working memory. If the name is a defclass name, the Java objects will be removed from working memory as well.

Parameters:
name - the name of a template
Throws:
JessException - if anything goes wrong

modify

public Fact modify(Fact fact,
                   java.lang.String slotName,
                   Value slotValue)
            throws JessException
Modify one slot in a fact. This function works for both plain and shadow facts. For shadow facts, the corresponding Java object is also modified. Uses the global context to resolve the value.

Parameters:
fact - a fact that's currently in working memory
slotName - the name of a slot in the fact
slotValue - a new value for the named slot
Returns:
the fact argument
Throws:
JessException - if the slot name is bad or any other error occurs

modify

public Fact modify(Fact fact,
                   java.lang.String slotName,
                   Value slotValue,
                   Context context)
            throws JessException
Modify one slot in a fact. This function works for both plain and shadow facts. For shadow facts, the corresponding Java object is also modified. Uses the supplied context to resolve the value.

Parameters:
fact - a fact that's currently in working memory
slotName - the name of a slot in the fact
slotValue - a new value for the named slot
context - an execution context
Returns:
the fact argument
Throws:
JessException - if the slot name is bad or any other error occurs

modify

public Fact modify(Fact fact,
                   java.lang.String[] slotNames,
                   Value[] slotValues)
            throws JessException
Modify any number of slots in a fact. This function works for both plain and shadow facts. For shadow facts, the corresponding Java object is also modified. Uses the global context to resolve the values.

Parameters:
fact - a fact that's currently in working memory
slotNames - the names of some slots in the fact
slotValues - new values for the named slots
Returns:
the fact argument
Throws:
JessException - if any slot name is bad or any other error occurs

modify

public Fact modify(Fact fact,
                   java.lang.String[] slotNames,
                   Value[] slotValues,
                   Context context)
            throws JessException
Modify any number of slots in a fact. This function works for both plain and shadow facts. For shadow facts, the corresponding Java object is also modified. Uses the given context to resolve the values.

Parameters:
fact - a fact that's currently in working memory.
slotNames - the names of some slots in the fact
slotValues - new values for the named slots.
context - the execution context
Returns:
the fact argument
Throws:
JessException - if any slot name is bad or any other error occurs

findFactByID

public Fact findFactByID(int id)
                  throws JessException
Return a Fact object given its numeric fact-id. This method 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
Find a Fact object in working memory, given a Fact object that is identical to it. 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 in working memory -- only a Fact object identical to one that is.

Parameters:
f - a fact
Returns:
a fact from working memory, or null if none
Throws:
JessException - if something goes wrong

mark

public WorkingMemoryMarker mark()
Return a marker for the current state of working memory. The marker can later be used to retract all facts asserted since the marker was placed using resetToMark().

Returns:
a marker
See Also:
resetToMark(WorkingMemoryMarker)

resetToMark

public void resetToMark(WorkingMemoryMarker marker)
                 throws JessException
Restore working memory by retracting all facts asserted after the given marker was placed.

Parameters:
marker - the marker
Throws:
JessException - if anything goes wrong
See Also:
mark()

getObjects

public java.util.Iterator getObjects(Filter filter)
Return a subset of Java objects (definstances) in working memory. The Iterator will include only those objects for which the Filter.accept(java.lang.Object) method returns true.

Parameters:
filter - a filter to apply to working memory
Returns:
an Iterator over the selected objects

ppFacts

public void ppFacts(java.lang.String head,
                    java.io.Writer output)
             throws java.io.IOException
Pretty-print all the facts with the given head to the Writer. Output is in Jess rule language format.

Parameters:
head - the name or "head" of the facts of interest
output - the Writer to send the data to
Throws:
java.io.IOException - if anything goes wrong

ppFacts

public void ppFacts(java.lang.String head,
                    java.io.Writer output,
                    boolean inXML)
             throws java.io.IOException
Pretty-print all the facts with the given head to the Writer. Output is either in Jess rule language format or in XML, depending on the value of the inXML parameter. XML files will be a complete well-formed document with a "fact-list" root element.

Parameters:
head - the name or "head" of the facts of interest
output - the Writer to send the data to
inXML - true for XML output, false for Jess language output
Throws:
java.io.IOException - if anything goes wrong

ppFacts

public void ppFacts(java.io.Writer output)
             throws java.io.IOException
Pretty-print all the facts in working memory to the Writer. Output is in the Jess rule language format.

Parameters:
output - the Writer to send the data to
Throws:
java.io.IOException - if anything goes wrong

ppFacts

public void ppFacts(java.io.Writer output,
                    boolean inXML)
             throws java.io.IOException
Pretty-print all the facts in working memory to the Writer. Output is either in Jess rule language format or in XML, depending on the value of the inXML parameter. XML files will be a complete well-formed document with a "fact-list" root element.

Parameters:
output - the Writer to send the data to
inXML - true for XML output, false for Jess language output
Throws:
java.io.IOException - if anything goes wrong

listDeffacts

public java.util.Iterator listDeffacts()
Return an Iterator over all the deffacts in this engine.

Returns:
the iterator

findDeffacts

public Deffacts findDeffacts(java.lang.String name)
Return the named deffacts object.

Parameters:
name - the name of a deffacts construct
Returns:
a Deffacts, or null if none

listDeftemplates

public java.util.Iterator listDeftemplates()
Return an Iterator over all the deftemplates in this engine, both explicit and implied.

Returns:
the iterator

listDefrules

public java.util.Iterator listDefrules()
Return an Iterator over all the rules and queries defined in this engine.

Returns:
the iterator

listFacts

public java.util.Iterator listFacts()
Return an Iterator over all the facts currently in working memory. The facts are returned in fact-id order.

Returns:
the iterator

listDefinstances

public java.util.Iterator listDefinstances()
Return an Iterator over all the Java objects currently represented by shadow facts in working memory.

Returns:
the iterator

containsObject

public boolean containsObject(java.lang.Object o)
Indicates whether a given object is being held in working memory. Will return true only for the same physical object, and not for distinct but equal() objects.

Parameters:
o - the object
Returns:
true if the object is in working memory

listDefclasses

public java.util.Iterator listDefclasses()
Return an Iterator over all the names of all defclasses. You can use each name to look up the corresponding template using findDeftemplate, or the corresponding Java class using javaClassForDefclass.

Returns:
the iterator
See Also:
findDeftemplate(java.lang.String), javaClassForDefclass(java.lang.String)

listDefglobals

public java.util.Iterator listDefglobals()
Return an Iterator over all the defglobals in this engine.

Returns:
the iterator

listFunctions

public java.util.Iterator listFunctions()
Return an Iterator over all special functions defined in this engine, including user-defined Java functions, deffunctions, functions defined in the Jess script library, imported static functions, but not including the built-in (intrinsic) functions. All the objects returned by the iterator implement the Userfunction interface.

Returns:
the iterator

listDeffunctions

public java.util.Iterator listDeffunctions()
Return an Iterator over all deffunctions defined in this engine, including the ones defined in the script library. The Iterator returns Deffunction objects.

Returns:
the iterator

findDefrule

public final HasLHS findDefrule(java.lang.String name)
Find a defrule or defquery object with a certain name.

Parameters:
name - the name
Returns:
the found rule or query, or null.

javaClassForDefclass

public java.lang.Class javaClassForDefclass(java.lang.String name)
Return the Java Class corresponding to a given Defclass name, or null if the name was not found.

Parameters:
name - the name of a defclass
Returns:
the Class object used to define that defclass

findDeftemplate

public Deftemplate findDeftemplate(java.lang.String name)
                            throws JessException
Find a deftemplate object with a certain name.

Parameters:
name - the name
Returns:
the deftemplate, or null
Throws:
JessException

createDeftemplate

public Deftemplate createDeftemplate(java.lang.String name)
                              throws JessException
Find or create the deftemplate by the given name. If there is no such deftemplate, an ordered template is created.

Parameters:
name - the "head" of the template
Returns:
a Deftemplate object
Throws:
JessException - if the template name is invalid

addDeftemplate

public Deftemplate addDeftemplate(Deftemplate dt)
                           throws JessException
Creates a new deftemplate in this rule engine. Ensures that every deftemplate has a unique name by rejecting duplicates.

Parameters:
dt - a new Deftemplate
Returns:
the argument
Throws:
JessException - if the deftemplate is already defined

removeDeftemplate

public void removeDeftemplate(java.lang.String name)
                       throws JessException
Removes an unused deftemplate from this engine, and from all peered engines. If the template is not found, return silently. If the template is found but is in use, will throw an exception.

Parameters:
name - the name of the template, optionally including a module
Throws:
JessException

addDeffacts

public Deffacts addDeffacts(Deffacts df)
                     throws JessException
Add a deffacts construct to this rule engine.

Parameters:
df - a new Deffacts object
Returns:
the argument
Throws:
JessException - If an error occurs during event broadcasting

removeDeffacts

public void removeDeffacts(java.lang.String name)
                    throws JessException
Remove a deffacts construct from this engine and any peers. The deffacts' facts are not removed from working memory until the engine is reset.

Parameters:
name - the name of the deffacts
Throws:
JessException

addDefglobal

public Defglobal addDefglobal(Defglobal dg)
                       throws JessException
Creates a new Defglobal in this rule engine. This defglobal will be reset immediately, regardless of the setting of resetGlobals.

Parameters:
dg - a new Defglobal object
Returns:
the argument
Throws:
JessException - if an error occurs

addDefglobals

public java.util.List addDefglobals(java.util.List dg)
                             throws JessException
Adds a list of Defglobals to this object, as if by addDefglobal().

Parameters:
dg - a List of Defglobals
Returns:
the argument
Throws:
JessException - if an error occurs

findDefglobal

public Defglobal findDefglobal(java.lang.String name)
Look up a defglobal by name. The name should include the leading and trailing asterisk required for defglobals.

Parameters:
name - the name of the defglobal
Returns:
the Defglobal, if found, or null

removeDefglobal

public void removeDefglobal(java.lang.String name)
                     throws JessException
Removes the given defglobal from this engine. The name sbould include the leading and trailing asterisks. This method returns silently if the defglobal is not found. Note that this method should not be used with peered engines; attempting to undefine a defglobal in a peered engine will result in an exception.

Parameters:
name - the name of the defglobal
Throws:
JessException - if anything goes wrong

removeUserDefinedFunctions

public void removeUserDefinedFunctions()
Removes all user-defined functions from this engine. Only the built-in functions and static methods from java.lang will remain.


addUserfunction

public Userfunction addUserfunction(Userfunction uf)
Creates a new function in this rule engine. Any existing function by the same name will be replaced. Built-in functions can be redefined this way.

Parameters:
uf - a new Userfunction
Returns:
the parameter, or null if call rejected by event handler

removeUserfunction

public void removeUserfunction(java.lang.String name)
Remove any currently defined function by the given name. Even built-in functions can be removed this way.

Parameters:
name - the name of the function to remove

addUserpackage

public Userpackage addUserpackage(Userpackage up)
Add a Userpackage to this engine. A Userpackage is a collection of Userfunctions. 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 by the given name.

Parameters:
name - the name of the function
Returns:
the Userfunction object, if there is one, or null.

addDefrule

public final HasLHS addDefrule(HasLHS dr)
                        throws JessException
Add a rule or query to this engine. The rule is compiled and added to the Rete network. Any existing rule or query by the same name is removed first.

Parameters:
dr - a Defrule or Defquery
Returns:
the added object
Throws:
JessException - if anything goes wrong

unDeffacts

public final Value unDeffacts(java.lang.String name)
Remove a deffacts from the engine. If the given name is "*", remove all deffacts.

Parameters:
name - the name of an existing deffacts construct, or "*"
Returns:
the symbol TRUE

unDefrule

public final Value unDefrule(java.lang.String name)
                      throws JessException
Deprecated. As of Jess 7.1, use removeDefrule(String)

Remove a rule or query from this Rete object. Removes all subrules of the named rule as well.

Parameters:
name - the name of the rule or query
Returns:
the symbol TRUE
Throws:
JessException - if anything goes wrong

removeDefrule

public void removeDefrule(java.lang.String name)
                   throws JessException
Remove a rule or query from this Rete object. Removes all subrules of the named rule as well.

Parameters:
name - the name of the rule or query
Throws:
JessException - if anything goes wrong

addDefmodule

public void addDefmodule(Defmodule module)
                  throws JessException
Define a new module, which becomes current. The current module is the one to which new constructs will be added.

Parameters:
module - a new Defmodule object
Throws:
JessException

addDefmodule

public void addDefmodule(java.lang.String name)
                  throws JessException
Deprecated. As of Jess 7, use addDefmodule(Defmodule).

Define a new module, which becomes current. The current module is the one to which new constructs will be added.

Throws:
JessException

addDefmodule

public void addDefmodule(java.lang.String name,
                         java.lang.String comment)
                  throws JessException
Deprecated. As of Jess 7, use addDefmodule(Defmodule).

Define a new module, which becomes current. The current module is the one to which new constructs will be added.

Throws:
JessException

removeDefmodule

public void removeDefmodule(java.lang.String name)
                     throws JessException
Remove the given defmodule from this engine and all peered engines. If the module is not found, return silently. Only empty modules can be removed; you must remove all the rules and templates defined in the module first, or an exception will be thrown.

Parameters:
name -
Throws:
JessException

getCurrentModule

public java.lang.String getCurrentModule()
Return the name of the current module. The current module is the one to which new constructs will be added.


setCurrentModule

public java.lang.String setCurrentModule(java.lang.String name)
                                  throws JessException
Change the current module. The current module is the one to which new constructs will be added.

Parameters:
name - the name of the new current module
Returns:
the old current module
Throws:
JessException - if the name is not a module

listModules

public java.util.Iterator listModules()
List all modules.

Returns:
an iterator over the names of all modules

getFocus

public java.lang.String getFocus()
Query the focus module. The focus module is the one from which rules are being fired.

Returns:
the name of the current focus module

setFocus

public void setFocus(java.lang.String name)
              throws JessException
Change the focus module. The focus module is the one from which rules are being fired.

Parameters:
name - the module that should get focus
Throws:
JessException

listFocusStack

public java.util.Iterator listFocusStack()
                                  throws JessException
Iterate over the module focus stack, from bottom to top. The current focus module is returned last. The focus module is the one from which rules are being fired.

Returns:
the iterator
Throws:
JessException

clearFocusStack

public void clearFocusStack()
Empty the module focus stack. The focus module is the one from which rules are being fired.


popFocus

public java.lang.String popFocus(java.lang.String expected)
                          throws JessException
Remove the top module from the focus stack, and return it. If expected in non-null, then this is a no-op unless expected names the top module on the stack. The focus module is the one from which rules are being fired.

Parameters:
expected - the expected module, or null
Returns:
the name of the module on top the focus stack
Throws:
JessException

verifyModule

public void verifyModule(java.lang.String name)
                  throws JessException
Throw an exception if the argument isn't the name of a module.

Parameters:
name - a proposed module name
Throws:
JessException

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.

Parameters:
name - a module name

findModule

public Defmodule findModule(java.lang.String name)
                     throws JessException
Return the Defmodule object corresponding to the Jess module with the given name.

Parameters:
name -
Returns:
Throws:
JessException

hasActivations

public boolean hasActivations()
                       throws JessException
Check whether the current module includes any activations to fire.

Returns:
true if there are activations in the current module
Throws:
JessException - if something goes wrong

hasActivations

public boolean hasActivations(java.lang.String moduleName)
                       throws JessException
Check whether there are any activations to fire in the named module. "*" is not accepted.

Parameters:
moduleName - a valid module name
Returns:
true if there are activations in the named module
Throws:
JessException - if the module name is invalid

listActivations

public java.util.Iterator listActivations()
                                   throws JessException
Return an Iterator over all the activations 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. This is an expensive operation.

Returns:
an iterator over the agenda for the current module
Throws:
JessException

listActivations

public java.util.Iterator listActivations(java.lang.String moduleName)
                                   throws JessException
Return an Iterator over all the activations for the named module. Asterisk ("*") is not accepted, in firing order. This is an expensive operation.

Parameters:
moduleName - the name of a module
Returns:
an iterator over the agenda for the named module
Throws:
JessException - if the module name is invalid

peekNextActivation

public Activation peekNextActivation()
                              throws JessException
Return the next activation record from the agenda. It's possible that this rule will be wrong if something happens to change the agenda before this rule fires.

Returns:
the next activation that will fire
Throws:
JessException - if anything goes wrong

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.

Returns:
the activation lock
See Also:
waitForActivations()

waitForActivations

public void waitForActivations()
Waits on the activation lock as long as the agenda is empty. Will return as soon as a rule is actvated. 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
Tell this engine to use the given Strategy object to order the rules on the agenda. You can implement your own strategies.

Parameters:
s - the new conflict resolution strategy
Returns:
the name of the previous conflict resolution strategy
Throws:
JessException

getStrategy

public Strategy getStrategy()
Retrieve the Strategy object this engine is using to order activations on the agenda.

Returns:
the current conflict resolution strategy

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, which helps determine the priority of rule firing. Returns one of the constants INSTALL, ACTIVATE, or EVERY_TIME.

Returns:
the salience evaluation behaviour
See Also:
setEvalSalience(int)

run

public int run()
        throws JessException
Run the rule engine. When the engine is running, rules are continuously removed from the agenda and fired in priority order; the order is determined by the current conflict resolution strategy.

Returns:
the actual number of rules fired
Throws:
JessException - if anything goes wrong

aboutToFire

protected void aboutToFire(Activation a)
Allows a subclass to be notified immediately before a rule fires. Subclasses can override this method to receive this notification.

Parameters:
a - the activation record for the about-to-fire rule

justFired

protected void justFired(Activation a)
Allows a subclass to be notified immediately after a rule fires. Subclasses can override this method to receive this notification.

Parameters:
a - the activation record for the just-fired rule

run

public int run(int max)
        throws JessException
Run the rule engine. If the number of rules fired becomes greater than the argument, the engine stops. When the engine is running, rules are continuously removed from the agenda and fired in priority order; the order is determined by the current conflict resolution strategy.

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 the rule engine until halt() is called. When no rules are active, the calling Thread will be waiting on the activation semaphore. When the engine is running, rules are continuously removed from the agenda and fired in priority order; the order is determined by the current conflict resolution strategy.

Returns:
The number of rules that fired.
Throws:
JessException - if an error occurs

halt

public void halt()
          throws JessException
Stop the engine from firing rules.

Throws:
JessException - if an error occurs during event propagation

isHalted

public boolean isHalted()
Returns true if halt has been called since the last run() call.

Returns:
true if the engine is halted

getThisRuleName

public java.lang.String getThisRuleName()
Find out the name of the currently firing rule.

Returns:
The name of the rule that is currently firing, if this is called while a rule is firing; otherwise, returns null.
See Also:
getThisActivation()

getThisActivation

public Activation getThisActivation()
Get the activation record for the currently firing rule. An activation record contains a Defrule and the list of facts that made the rule active.

Returns:
the activation record for the rule that is currently firing, if this is called while a rule is firing; otherwise, returns null.
See Also:
getThisRuleName()

getRunThread

public java.lang.Thread getRunThread()
If this engine is currently firing a rule, returns the Thread that the rule is firing on; otherwise, returns null.

Returns:
the thread
See Also:
getThisActivation()

addJessListener

public void addJessListener(JessListener jel)
Register an event listener with this rule engine. The listener will be notified of various significant events according to the value of the event mask for this engine. Events are generally delivered immediately before an action occurs, so that the listener can veto the event by throwing an exception.

Parameters:
jel - a callback object that implements JessListener
See Also:
JessEvent, setEventMask(int)

removeJessListener

public void removeJessListener(JessListener jel)
Remove an event listener from this rule engine. The listener will no longer be notified of events.

Parameters:
jel - a previously-registered callback object
See Also:
addJessListener(JessListener)

listJessListeners

public java.util.Iterator listJessListeners()
Returns an iterator over all previously registered event listeners.

Returns:
the Iterator
See Also:
addJessListener(JessListener)

getEventMask

public int getEventMask()
Query the current value of the event mask.

Returns:
the event mask
See Also:
setEventMask(int)

setEventMask

public void setEventMask(int mask)
You can control which events this object will fire using this method. The argument is the result of logical-OR-ing together some of the constants in the JessEvent class. By default, the event mask is 0 and no events are sent.

Parameters:
mask - the new event mask
See Also:
getEventMask()

setPassiveMode

public void setPassiveMode(boolean passiveMode)
Return whether the engine is in passive mode. In passive mode, the engine won't send added rules to the compiler. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
passiveMode - the desired value of this property

isDebug

public boolean isDebug()
Return whether the engine is in debug mode. In debug mode, the engine can single-step. Special JessEvents are used for this purpose. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Returns:
whether the engine is in debug mode

setDebug

public void setDebug(boolean debug)
Specify whether the engine should be in debug mode. In debug mode, the engine can single-step. Special JessEvents are used for this purpose. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
debug - the desired state

recordFunction

public static void recordFunction(Funcall fc,
                                  java.lang.String fileName,
                                  int lineno)
Store a debug symbol for a function call. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
fc - the funcall being invoked
fileName - the source file name
lineno - the source file line number

recordFunction

public static void recordFunction(Funcall fc,
                                  LineNumberRecord lnr)
Store a debug symbol for a function call. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
fc - the funcall being invoked
lnr - the source file name and line number

lookupFunction

public static LineNumberRecord lookupFunction(Funcall fc)
Return information about the source location of a given function call, if known. This method only works when the engine is in debug mode. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
fc - the funcall
Returns:
source file and line number information, if known, or null

removeDebugListener

public void removeDebugListener(JessListener jel)
Remove a listener so that it will no longer receive debug events. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
jel - the listener to remove

addDebugListener

public void addDebugListener(JessListener jel)
Add a listener so that it will receive debug events. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Parameters:
jel - the listener to remove

listDebugListeners

public java.util.Iterator listDebugListeners()
Return an iterator over all listeners that will receive debug events. This is used by the JessDE implementation, but isn't useful to the vast majority of clients.

Returns:
the iterator

bload

public void bload(java.io.InputStream is)
           throws java.io.IOException,
                  java.lang.ClassNotFoundException
Read this object's state from the given stream. Similar to the readObject() method used in Serialization, except it loads new state into an existing object. The data on the InputStream must have been written by a call to bsave().

Parameters:
is - an InputStream
Throws:
java.io.IOException
java.lang.ClassNotFoundException

bsave

public void bsave(java.io.OutputStream os)
           throws java.io.IOException
Save this object's state out to the given stream. Similar to the writeObject() method used in serialization, but only writes the state of this object, not the object itself. You can read this into another Rete object using the bload() method.

Parameters:
os - an OutputStream
Throws:
java.io.IOException

definstance

public Value definstance(java.lang.String jessTypename,
                         java.lang.Object object,
                         boolean dynamic)
                  throws JessException
Make a shadow fact for the given object and add it to working memory. The boolean argument indicates whether or not to install a PropertyChangeListener to listen for change events. Uses the global context, which is usually what you want.

Parameters:
jessTypename - the name of a defclass
object - a Java object of the defclass's type
dynamic - true if PropertyChangeListeners should be used
Returns:
a FactIdValue containing the shadow fact for the object
Throws:
JessException - if anything goes wrong

definstance

public Value definstance(java.lang.String jessTypename,
                         java.lang.Object object,
                         boolean dynamic,
                         Context context)
                  throws JessException
Make a shadow fact for the given object and add it to working memory. The boolean argument indicates whether or not to install a PropertyChangeListener to listen for change events.

Parameters:
jessTypename - the name of a defclass
object - a Java object of the defclass's type
dynamic - true if PropertyChangeListeners should be used
context - used for asserting the fact
Returns:
a FactIdValue containing the shadow fact for the object
Throws:
JessException - if anything goes wrong

getShadowFactForObject

public Fact getShadowFactForObject(java.lang.Object o)
                            throws JessException
Returns the "shadow fact" that represents the given object in working memory.

Parameters:
o - an object in working memory
Returns:
the shadow fact representing that object
Throws:
JessException - if the given object is not in working memory

remove

public Fact remove(java.lang.Object object)
            throws JessException
Remove the given object from working memory. Tell this engine to stop pattern matching on the given object, and retract the shadow fact.

Parameters:
object - an object currently represented in working memory.
Returns:
the shadow fact for the object
Throws:
JessException - if object isn't a definstanced object, or on error
See Also:
add(java.lang.Object), undefinstance(Object)

undefinstance

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

Remove the given object from working memory. Tell this engine to stop pattern matching on the given object, and retract the shadow fact.

A synonym for "remove".

Parameters:
object - an object currently represented in working memory.
Returns:
the shadow fact for the object
Throws:
JessException - if object isn't a definstanced object, or on error
See Also:
add(Object), remove(Object)

updateObject

public Value updateObject(java.lang.Object object)
                   throws JessException
Bring a shadow fact up to date. If the properties of the given object, assumed to be a definstanced object, have changed, its corresponding shadow fact will be updated.

Parameters:
object - a previously definstanced object
Returns:
the shadow fact, as a FactIDValue
Throws:
JessException - if object isn't a definstanced object, or on error

updateObject

public Value updateObject(java.lang.Object object,
                          Context context)
                   throws JessException
Throws:
JessException

updateObject

public Value updateObject(java.lang.Object object,
                          java.lang.String slotName)
                   throws JessException
Bring one slot of a shadow fact up to date. If the named property of the given object, assumed to be a definstanced object, has changed, its corresponding shadow fact will be updated.

Parameters:
object - a previously definstanced object
slotName - the name of a property of that object
Returns:
the shadow fact, as a FactIDValue
Throws:
JessException - if object isn't a definstanced object, or on error

add

public Value add(java.lang.Object o)
          throws JessException
Add an object to working memory using various defaults. In this implementation, Jess assumes you want to use an existing deftemplate with the same name as the class of this object, minus the package names. If no such deftemplate exists, one is created. The object is added with automatic support for PropertyChangeEvents if they are generated by the object.

Parameters:
o - an object to add to working memory
Returns:
the shadow fact, as a FactIdValue
Throws:
JessException - if anything goes wrong
See Also:
remove(Object), undefinstance(Object)

addAll

public void addAll(java.util.Collection c)
            throws JessException
Add a collection of objects to working memory. Calls add(Object) on each item in the collection.

Parameters:
c - a collection of objects to be added to working memory
Throws:
JessException - if anything goes wrong
See Also:
add(Object), removeAll(java.util.Collection)

removeAll

public void removeAll(java.util.Collection c)
               throws JessException
Remove a collection of objects from working memory. Calls remove(Object) on each item in the collection.

Parameters:
c - a collection of objects to be removed from working memory
Throws:
JessException - if anything goes wrong
See Also:
remove(Object), add(Object)

addAll

public void addAll(java.util.Iterator it)
            throws JessException
Add a collection of objects to working memory. Calls add(Object) on each item in the collection.

Parameters:
it - Iterator over a collection of objects to be added to working memory
Throws:
JessException - if anything goes wrong
See Also:
add(Object)

defclass

public Value defclass(java.lang.String jessName,
                      java.lang.String clazz,
                      java.lang.String parent,
                      boolean includeMemberVariables)
               throws JessException
Add a defclass definition (a deftemplate) to this engine. One slot is included for each JavaBeans property of the class. In addition, slots representing public member variables can be included.

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
includeMemberVariables - if true, slots corresponding to public member variables are created.
Throws:
JessException

defclass

public Value defclass(java.lang.String jessName,
                      java.lang.String clazz,
                      java.lang.String parent)
               throws JessException
Add a defclass definition (a deftemplate) to this engine. One slot will be created for each JavaBeans property of the class.

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
Throws:
JessException

getGlobalContext

public final Context getGlobalContext()
Fetch the global execution context. This gives you access to defglobals and variables defined at the global scope.

Returns:
The global execution context.

eval

public Value eval(java.lang.String cmd)
           throws JessException
Evaluate a Jess expression in this engine's global context. The result is returned as a jess.Value; you can use the methods of that class to extract the data. For example, here we define a deffunction and then call it, storing the result in an int variable:

 Rete r = new Rete();
 r.eval("(deffunction square (?n) (return (* ?n ?n)))");
 Value v = r.eval("(square 3)");
 int nine = v.intValue(r.getGlobalContext()));
 

Note that you may only pass one function call or construct at a time to eval().

Parameters:
cmd - a string containing a Jess expression
Returns:
the result of evaluating the expression
Throws:
JessException - if anything goes wrong

executeCommand

public Value executeCommand(java.lang.String cmd)
                     throws JessException
Deprecated. Use eval() instead.

Evaluate a Jess expression in this engine's global context. The result is returned as a jess.Value; you can use the methods of that class to extract the data.

Parameters:
cmd - a string containing a Jess expression
Returns:
the result of evaluating the expression
Throws:
JessException - if anything goes wrong
See Also:
eval(String)

eval

public Value eval(java.lang.String cmd,
                  Context context)
           throws JessException
Evaluate a Jess expression in the given execution context. The result is returned as a jess.Value; you can use the methods of that class to extract the data. For example, here we define a deffunction and then call it, storing the result in an int variable:

 Rete r = new Rete();
 r.eval("(deffunction square (?n) (return (* ?n ?n)))");
 Value v = r.eval("(square 3)");
 int nine = v.intValue(r.getGlobalContext()));
 

Note that you may only pass one function call or construct at a time to eval().

Parameters:
cmd - a string containing a Jess expression
context - the evaluation context
Returns:
the result of evaluating the expression
Throws:
JessException - if anything goes wrong

executeCommand

public Value executeCommand(java.lang.String cmd,
                            Context context)
                     throws JessException
Deprecated. Use eval() instead.

Evaluate a Jess expression in the given context. The result is returned as a jess.Value; you can use the methods of that class to extract the data.

Parameters:
cmd - a string containing a Jess expression
context - the evaluation context
Returns:
the result of evaluating the expression
Throws:
JessException - if anything goes wrong
See Also:
eval(String)

setResetGlobals

public final void setResetGlobals(boolean reset)
Set the resetGlobals property. When resetGlobals is true, the initializers of defglobals are evaluated when (reset) is executed. When it is false, (reset) doesn't reinitialize defglobals.

Parameters:
reset - The value of this property

getResetGlobals

public final boolean getResetGlobals()
Return the resetGlobals property. When resetGlobals is true, the initializers of defglobals are evaluated when (reset) is executed. When it is false, (reset) doesn't reinitialize defglobals.

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. The store and fetch methods provide a simple way to exchange data between Jess and Java. They give you easy access to a single HashMap from both languages, so you can use the HashMap as a "mailbox". Use store() or the Jess function (store) to save a value in this map; use fetch() or the Jess function (fetch) to retrieve the value.

Parameters:
name - a key under which to save 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. The store and fetch methods provide a simple way to exchange data between Jess and Java. They give you easy access to a single HashMap from both languages, so you can use the HashMap as a "mailbox". Use store() or the Jess function (store) to save a value in this map; use fetch() or the Jess function (fetch) to retrieve the value.

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)

fetch

public Value fetch(java.lang.String name)
Retrieve an object previously stored with store(). The store and fetch methods provide a simple way to exchange data between Jess and Java. They give you easy access to a single HashMap from both languages, so you can use the HashMap as a "mailbox". Use store() or the Jess function (store) to save a value in this map; use fetch() or the Jess function (fetch) to retrieve the value.

The result is returned as a jess.Value * object; you must use the methods of that class to extract the * underlying data.

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()
Return the Factory Jess will use to create Rete Tokens. This method allows extensions like FuzzyJess to use special augmented tokens to store additional information. The vast majority of clients will never use this method.

Returns:
the current Token Factory implementation

setFactory

public static void setFactory(Factory f)
Set the Factory Jess will use to create Rete Tokens. This method allows extensions like FuzzyJess to use special augmented tokens to store additional information. The vast majority of clients will never use this method.

Parameters:
f - a jess.Factory implementation

batch

public Value batch(java.lang.String filename)
            throws JessException
Execute a file of Jess language code or JessML code. Jess will look on the file system relative to the current directory, and also along the CLASSPATH, to find the named file. If Jess is running in an applet, the document base will also be checked.

Parameters:
filename - the name of a file or resource
Returns:
the value of the last item parsed from the file, or FALSE
Throws:
JessException - if there are I/O problems, or syntax errors in the file
See Also:
Batch.batch(java.lang.String, jess.Rete)

runQueryStar

public QueryResult runQueryStar(java.lang.String name,
                                ValueVector params)
                         throws JessException
Invoke the named query and return the results. The QueryResult has an API similar to java.sql.ResultSet. The global context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
Returns:
a QueryResult containing all the matches
Throws:
JessException - if anything goes wrong

runQueryStar

public QueryResult runQueryStar(java.lang.String name,
                                ValueVector params,
                                Context context)
                         throws JessException
Invoke the named query and return the results. The QueryResult has an API similar to java.sql.ResultSet. The given context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
Returns:
a QueryResult containing all the matches
Throws:
JessException - if anything goes wrong

runQuery

public java.util.Iterator runQuery(java.lang.String name,
                                   ValueVector params)
                            throws JessException
Deprecated. Since Jess 7.0, superceded by runQueryStar()

Invoke the named query and return an iterator over the matching results. Each match is a jess.Token object. The global context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
Returns:
an iterator over all results
Throws:
JessException - if anything goes wrong

runQuery

public java.util.Iterator runQuery(java.lang.String name,
                                   ValueVector params,
                                   Context context)
                            throws JessException
Deprecated. Since Jess 7.0, superceded by runQueryStar()

Invoke the named query and return an iterator over the matching results. Each match is a jess.Token object. The global context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
Returns:
an iterator over all results
Throws:
JessException - if anything goes wrong

countQueryResults

public int countQueryResults(java.lang.String name,
                             ValueVector params)
                      throws JessException
Invoke the named query and return the count of matching results. The global context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
Returns:
the count of matching results
Throws:
JessException - if anything goes wrong

countQueryResults

public int countQueryResults(java.lang.String name,
                             ValueVector params,
                             Context context)
                      throws JessException
Invoke the named query and return the count of matching results. The given context is used to resolve variables.

Parameters:
name - the name of the query
params - the query's parameters
context - an execution context
Returns:
the count of matching results
Throws:
JessException - if anything goes wrong

watch

public void watch(int which)
           throws JessException
Produce some debugging information. The argument specifies which kind of event will be reported. The output goes to the watch router, which is initially "WSTDOUT". You can set the watch router to anything you'd like.

Parameters:
which - one of the constants in WatchConstants
Throws:
JessException - if the argument is invalid
See Also:
WatchConstants, setWatchRouter(java.lang.String)

unwatch

public void unwatch(int which)
             throws JessException
Cancel some debugging information. The argument specifies which kind of event will no longer be reported.

Parameters:
which - one of the constants in WatchConstants
Throws:
JessException - if the argument is invalid
See Also:
WatchConstants

watchAll

public void watchAll()
Produce all possible debugging info. Equivalent to calling watch() multiple times using each legal argument in succession.


unwatchAll

public void unwatchAll()
Cancel all debugging info. Equivalent to calling unwatch() using each legal argument in succession.


eventHappened

public void eventHappened(JessEvent je)
Responds to a JessEvent by emitting "watch" messages. This method is just an implementation detail, part of the "watch" facility. Each Rete object is registered with itself as a listener.

Specified by:
eventHappened in interface JessListener
Parameters:
je - An event object

setWatchRouter

public java.lang.String setWatchRouter(java.lang.String s)
                                throws JessException
Sets the router the "watch" facility will use for output. The default is WSTDOUT. The named router must exist.

Parameters:
s - the name of the router to use
Returns:
the name of the previous watch router
Throws:
JessException - if the router doesn't exist

defineFeature

public void defineFeature(java.lang.String name)
Register a named feature, as if by the "provide" function. After calling this method, calling isFeatureDefined with the same argument will always return true.

Parameters:
name - the name of the feature

isFeatureDefined

public boolean isFeatureDefined(java.lang.String name)
Return whether a feature name has been registered by the "provide" function.

Parameters:
name - the name of the feature
Returns:
true if the feature is defined

getSupportingTokens

public java.util.List getSupportingTokens(Fact fact)
Returns a list of one or more jess.Token objects that provide logical support for this fact. This method returns null if there is no specific logical support. You can use the Token.size() method to check how many supporting Facts are in a Token, and the Token.fact() method to check each supporting Fact in turn. This is a fast operation, taking O(ln N) time, where N is the number of facts that have logical support.

Parameters:
fact - a fact of interest
Returns:
a list of supporting Token objects, or null if there is unconditional support
See Also:
Token, Token.fact(int), Token.size()

getSupportedFacts

public java.util.List getSupportedFacts(Fact supporter)
Returns a list of Fact objects that receive logical support from the argument. This method is potentially expensive, as it takes time proportional to O(N), where N is the number of facts currently receiving logical support of any kind.

Parameters:
supporter - a fact of interest
Returns:
a list of zero or more Fact objects

getApplet

public java.applet.Applet getApplet()
If this Rete object is part of an applet, and the applet was supplied as a constructor argument, then this method will return it.

Returns:
the Applet this Rete object is a part of, if any

getAppObjectClass

public java.lang.Class getAppObjectClass()
Return the Class that represents the "app object" for this Rete. This class's ClassLoader plays a special role: it is used to load classes named in Jess language code.

Returns:
the Class object whose ClassLoader will be used

setApplet

public void setApplet(java.applet.Applet applet)
Notify this Rete object that it is part of an Applet. The Applet becomes the "app object", and its ClassLoader will be used to load classes named in Jess code.

Parameters:
applet - the Applet

setAppObject

public void setAppObject(java.lang.Object appObject)
Specify the "app object" for this Rete. The app object's ClassLoader will be used to load classes named in Jess code. By default, a Rete object is its own app object.

Parameters:
appObject - the "app object".

setClassLoader

public void setClassLoader(java.lang.ClassLoader loader)
Specify the ClassLoader that will be used to load classes named in Jess code. By default, the context ClassLoader is used.

Parameters:
loader - the ClassLoader to use

getClassLoader

public java.lang.ClassLoader getClassLoader()
Return the ClassLoader that will be used to find classes named in Jess ocde. By default, the context ClassLoader is used.

Returns:
the ClassLoader used to load user classes

findClass

public java.lang.Class findClass(java.lang.String className)
                          throws java.lang.ClassNotFoundException
Load a class using the active ClassLoader. Previously loaded classes are cached. The import tables are used, so the given name doesn't have to be fully qualified.

Parameters:
className - the name of the class
Returns:
the Class object
Throws:
java.lang.ClassNotFoundException - if the class could not be loaded

getResource

public java.net.URL getResource(java.lang.String name)
Load a resource using the current ClassLoader's getResource() method.

Parameters:
name - the name of the resource
Returns:
a URL for the resource

importPackage

public void importPackage(java.lang.String pack)
Make all the classes in a package available for use in unqualified form from Jess code. The package name should include a trailing "." -- for example, "java.lang." .

Parameters:
pack - the name of a Java package

importClass

public void importClass(java.lang.String clazz)
                 throws JessException
Make a single class name available for use in unqualified form in Jess code. Also for each public static method and variable, create a Jess function with name of the form "Class.member" which, when called, defers to the given static member, either calling the method or reading the value of the variable.

Parameters:
clazz - the fully-qualified name of the class
Throws:
JessException - if the class is not found

getClassResearcher

public ClassResearcher getClassResearcher()
Return the ClassResearcher this engine will use to learn about Java classes mentioned in Jess code.

Returns:
the current class researcher

setClassResearcher

public void setClassResearcher(ClassResearcher researcher)
Set the ClassResearcher this engine will use to learn about Java classes mentioned in Jess code.

Parameters:
researcher -

toString

public java.lang.String toString()
Returns "[Rete]".

Overrides:
toString in class java.lang.Object
Returns:
the String "[Rete]".

getValueFactory

public ValueFactory getValueFactory()

Fetch the value factory for this engine. The value factory should be used as a source of jess.Value objects, because they are immutable and can be cached and shared. Using the ValueFactory will generally be more efficient than allocating your own objects.

Peered engines share a ValueFactory by default; otherwise each engine creates its own.

Returns:
the value factory used by this engine.
See Also:
ValueFactory, setValueFactory(ValueFactory)

setValueFactory

public void setValueFactory(ValueFactory factory)
Set the value factory used by this engine. You can create your own custom subclass of ValueFactory to implement your own caching, logging, or tracing scheme.

Parameters:
factory - the new factory
See Also:
getValueFactory()

getMemberChar

public char getMemberChar()
The character used to denote memberhood in "Java patterns." Normally a period, but can be changed to allow dots in slot names (for example.)


setMemberChar

public void setMemberChar(char c)
Change the character that denotes a member in "Java patterns."


© 2008 Sandia Corporation