jess
Class Rete

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.

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.

LIBRARY_NAME

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.

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.

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.

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

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.

clear

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.

reset

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.

assertFact

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.

assertFact

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.

modify

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.

modify

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.

findFactByFact

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.

ppFacts

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

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.

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.

removeDefglobal

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.

removeDefmodule

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.

popFocus

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.

listActivations

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.

setEvalSalience

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.

run

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.

runUntilHalt

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.

addJessListener

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.

getEventMask

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.

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.

lookupFunction

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.

bload

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

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.

add

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.

eval

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:

eval

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:

store

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.

store

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.

fetch

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.

clearStorage

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

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

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

watch

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.

getSupportingTokens

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

getSupportedFacts

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.

importClass

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.

toString

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.