jess
Class Fact

java.lang.Object
  jess.ValueVector
      jess.Fact

All Implemented Interfaces:

java.lang.Cloneable, Modular, Named, java.io.Serializable, Visitable

public class Fact

extends ValueVector

implements java.io.Serializable, Modular, Visitable

A Fact is the fundamental unit of information in Jess's working memory. A Fact is stored as a list in which all the entries correspond to slots. The head or name of the fact is stored in a separate variable (available via the getName() method.)

To construct a Fact, you must specify the "head" either as a String to the constructor, or by specifying the deftemplate to use. Then you have to populate the slots using setSlotValue(java.lang.String, jess.Value). Finally, you can add it to a Rete object's working memory using the Rete.assertFact(jess.Fact) method.

Constructing an Unordered Fact from Java

In the following example, we create a template and assert an unordered fact that uses it.

 Rete r = new Rete();
 r.eval("(deftemplate point \"A 2D point\" (slot x) (slot y))");

 Fact f = new Fact("point", r);
 f.setSlotValue("x", new Value(37, RU.INTEGER));
 f.setSlotValue("y", new Value(49, RU.INTEGER));
 r.assertFact(f);
 

Constructing an Unordered Fact from Java

In this example, the template has a multislot. In Java, a multislot is represented by a Value of type RU.LIST. The Value object contains a ValueVector containing the fields of the multislot.

 Rete r = new Rete();
 r.eval("(deftemplate vector \"A named vector\" (slot name) (multislot list))");

 Fact f = new Fact("vector", r);
 f.setSlotValue("name", new Value("Groceries", RU.SYMBOL));
 ValueVector vv = new ValueVector();
 vv.add(new Value("String Beans", RU.STRING));
 vv.add(new Value("Milk", RU.STRING));
 vv.add(new Value("Bread", RU.STRING));
 f.setSlotValue("list", new Value(vv, RU.LIST));
 r.assertFact(f);
 

Constructing an Ordered Fact from Java

An ordered fact is actually represented as an unordered fact with a single slot: a multislot named __data. You don't need to create a template for an ordered fact: one will be created automatically if it doesn't already exist.

Once you assert a jess.Fact object, you no longer "own" it - it becomes part of the Rete object's internal data structures. As such, you must not change the values of any of the Fact's slots. If you retract the fact, the Fact object is released and you are free to alter it as you wish. Alternatively, you can use the method Rete.modify(jess.Fact, java.lang.String, jess.Value) to modify a fact.

(C) 2006 Sandia National Laboratories

See Also:

Serialized Form

Field Summary

static int	DYNAMIC Return value from getShadowMode() that indicates a Fact is a dynamic shadow fact.
static int	NO Return value from getShadowMode() that indicates a Fact is not a shadow fact.
static int	STATIC Return value from getShadowMode() that indicates a Fact is a static shadow fact.

Fields inherited from class jess.ValueVector

m_ptr, m_v

Constructor Summary

Fact(Deftemplate template)
Basic constructor.

Fact(Fact f)
Create a Fact from another Fact.

Fact(java.lang.String name, Rete engine)
Basic constructor.

Method Summary

java.lang.Object	accept(Visitor v) A proper accept() implementation should call one of the visitXXX() methods on the Visitor.
java.lang.Object	clone() Make a copy of this fact
boolean	equals(java.lang.Object o) Compare this Fact to another Fact to determine their equality.
Value	get(int i) Returns the entry at position i in this ValueVector.
java.lang.String	getConstructType() Return the String "fact".
Deftemplate	getDeftemplate() Return the deftemplate for this fact.
java.lang.String	getDocstring() Always returns null
int	getFactId() Returns this Fact's fact-id.
Fact	getIcon() Return the canonical representation of this Fact object.
java.lang.String	getModule() Return the name of the module this fact is a member of.
java.lang.String	getName() Returns the name or "head" of this Fact.
int	getShadowMode() Indicates whether this fact is a shadow fact, and if so, what type.
Value	getSlotValue(java.lang.String slotname) Return the value from the named slot.
int	getTime() Return the "pseudotime" at which this Fact was asserted or last modified.
int	hashCode() Return a hash code for this fact based on its name and the contents of all of its slots.
boolean	isShadow() Indicates whether this Fact is a "shadow fact".
void	setSlotValue(java.lang.String slotname, Value value) Set the value in the named slot.
java.lang.String	toString() Pretty-print this fact into a String.
java.lang.String	toStringWithParens() Pretty-print this fact into a String.

Methods inherited from class jess.ValueVector

add, add, add, add, add, add, add, addAll, addAll, cloneInto, copy, remove, set, setLength, size

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NO

public static final int NO

Return value from getShadowMode() that indicates a Fact is not a shadow fact.

See Also:

Constant Field Values

DYNAMIC

public static final int DYNAMIC

Return value from getShadowMode() that indicates a Fact is a dynamic shadow fact. A dynamic shadow fact is one that is updated by PropertyChangeEvents from its corresponding JavaBean.

See Also:

Constant Field Values

STATIC

public static final int STATIC

Return value from getShadowMode() that indicates a Fact is a static shadow fact. A static shadow fact is one that is not registered to receive PropertyChangeEvents.

See Also:

Constant Field Values

Constructor Detail

Fact

public Fact(Deftemplate template)
     throws JessException

Basic constructor. If the deftemplate is an unordered deftemplate, default values are copied from the deftemplate.

Parameters:

template - the deftemplate to use

Throws:

JessException - if anything goes wrong

Fact

public Fact(java.lang.String name,
            Rete engine)
     throws JessException

Basic constructor. If name is not a known deftemplate, an implied ordered deftemplate is created. If it is a known unordered deftemplate, default values are copied from the deftemplate.

After you create a Fact, you can populate its slots using the setSlotValue() method.

Parameters:

name - the head or name of the fact

engine - the engine in which to find the deftemplate

Throws:

JessException - if anything goes wrong

Fact

public Fact(Fact f)
     throws JessException

Create a Fact from another Fact. No default values are filled in; the Fact is assumed to already be complete.

Parameters:

f - another Fact object to copy

Throws:

JessException - if anything goes wrong

Method Detail

getIcon

public Fact getIcon()

Return the canonical representation of this Fact object. For most Facts, this returns "this", but for certain Facts -- in particular, for Facts extracted from jess.Token objects -- it may return another object. If you are examining a jess.Token object and obtain a reference to a Fact from that Token, then call getIcon() to "canonicalize" that Fact before using it.

Returns:

the canonical version of this Fact

getName

public java.lang.String getName()

Returns the name or "head" of this Fact. For example, for the fact
(person (name Fred) (age 16)),
given that the "person" template is defined in the "MAIN" module, this method will return "MAIN::person".

Specified by:

getName in interface Named

Returns:

the name of this Fact.

getFactId

public int getFactId()

Returns this Fact's fact-id. Each Fact in a Rete object's working memory has a unique fact-id which is assigned when the Fact is asserted and doesn't change. Fact-id's start at 0 and increment from there.

Returns:

the fact-id

isShadow

public boolean isShadow()

Indicates whether this Fact is a "shadow fact". A shadow fact is the projection of a plain Java object into working memory. Regular facts -- non-shadow facts -- don't have an associated Java object.

Returns:

true is this is a shadow fact

getShadowMode

public int getShadowMode()

Indicates whether this fact is a shadow fact, and if so, what type. Shadow facts can be "dynamic", in which case property change events from the Java object will be used to update the fact, or "static", in which case no change events are expected.

Returns:

NO, DYNAMIC, or STATIC from this class

getDeftemplate

public final Deftemplate getDeftemplate()

Return the deftemplate for this fact. The jess.Deftemplate object determines the name of the fact and the names and properties of all its slots.

Returns:

the deftemplate for this fact

getModule

public final java.lang.String getModule()

Return the name of the module this fact is a member of. Every fact belongs to a module, either the default module MAIN or another user-defined module.

Specified by:

getModule in interface Modular

Returns:

the name of the module

getTime

public int getTime()

Return the "pseudotime" at which this Fact was asserted or last modified. Each Rete object counts pseudotime in increments that increase each time a fact is asserted or modified. Pseudotime is used in determining which rules will fire first.

Returns:

the pseudotime at which this Fact was asserted or last modified

get

public Value get(int i)
          throws JessException

Description copied from class: ValueVector

Returns the entry at position i in this ValueVector.

Overrides:

get in class ValueVector

Parameters:

i - the 0-based index of the Value to fetch

Returns:

the Value

Throws:

JessException

clone

public java.lang.Object clone()

Make a copy of this fact

Overrides:

clone in class ValueVector

Returns:

the copy

getSlotValue

public final Value getSlotValue(java.lang.String slotname)
                         throws JessException

Return the value from the named slot.

Parameters:

slotname - the name of a slot in this fact

Returns:

the value from the named slot

Throws:

JessException - if anything goes wrong

setSlotValue

public final void setSlotValue(java.lang.String slotname,
                               Value value)
                        throws JessException

Set the value in the named slot. If the slot is a multislot, and the value is not a list, then a list will be created to hold the single item.

Parameters:

slotname - the name of the slot

value - the new value for the slot

Throws:

JessException - if anything goes wrong

toString

public java.lang.String toString()

Pretty-print this fact into a String. Should always be a parseable fact, except when a slot holds a Java object.

Overrides:

toString in class ValueVector

Returns:

the pretty-printed String

toStringWithParens

public java.lang.String toStringWithParens()

Pretty-print this fact into a String. Should always be a parseable fact, except when a slot holds a Java object.

Overrides:

toStringWithParens in class ValueVector

Returns:

the pretty-printed String

equals

public boolean equals(java.lang.Object o)

Compare this Fact to another Fact to determine their equality. Two facts are equal if they are the same object, or they have the same name and their contents are the same.

Overrides:

equals in class ValueVector

Parameters:

o - a Fact to compare to

Returns:

true if the two Facts are equal

hashCode

public int hashCode()

Return a hash code for this fact based on its name and the contents of all of its slots.

Overrides:

hashCode in class ValueVector

Returns:

the hash code

getConstructType

public final java.lang.String getConstructType()

Return the String "fact".

Specified by:

getConstructType in interface Named

Returns:

the String "fact"

getDocstring

public final java.lang.String getDocstring()

Always returns null

Specified by:

getDocstring in interface Named

Returns:

null

accept

public java.lang.Object accept(Visitor v)

Description copied from interface: Visitable

A proper accept() implementation should call one of the visitXXX() methods on the Visitor.

Specified by:

accept in interface Visitable

Parameters:

v - a visitor to invoke

Returns:

whatever the invoked Visitor method returns.