jess
Class Fact

java.lang.Object
  extended by jess.ValueVector
      extended by jess.Fact
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Modular, Named, 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) 2013 Sandia Corporation

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.
 void checkConstraints()
          Throws an informative exception if slot constraints defined in this fact's template are violated by the slot values.
 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()
          Returns the documentation string for this fact's deftemplate
 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, contains, 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. This method should never be called on a Fact object that's been asserted into working memory, or the behavior is undefined (and generally bad;) use Rete.modify() instead.

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()
Returns the documentation string for this fact's deftemplate

Specified by:
getDocstring in interface Named
Returns:
a description of the template for this fact

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.

checkConstraints

public void checkConstraints()
                      throws JessException
Throws an informative exception if slot constraints defined in this fact's template are violated by the slot values.

Throws:
JessException - to indicate violated constraints

© 2013 Sandia Corporation