jess
Class Value

java.lang.Object
  extended by jess.Value
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
BindingValue, FactIDValue, FuncallValue, LongValue, Variable

public class Value
extends java.lang.Object
implements java.io.Serializable

The class jess.Value is probably the one you'll use the most in working with Jess. A Value is a self-describing data object. Every datum in Jess is contained in one. Once it is constructed, a Value's type and contents cannot be changed; it is immutable.

Value objects are constructed by specifying the data and (usually) the type. Each overloaded constructor assures that the given data and the given type are compatible. Note that for each constructor, more than one value of the type parameter may be acceptable.

jess.Value has a number of subclasses: Variable, FuncallValue, FactIDValue, and LongValue are the four of most interest to the reader. When you wish to create a value to represent a variable, a function call, a fact, or a Java long, you must use the appropriate subclass.

Note to the design-minded: We could have used a Factory pattern here and hidden the subclasses from the programmer; now backwards compatibility prevents us from hiding the constructors although a factory will probably be introduced eventually.

Value supports a number of functions to get the actual data out of a Valueobject. Some jess.Value objects may need to be resolved before use. To resolve a jess.Value means to interpret it in a particular context. jess.Value objects can represent both static values (symbols, numbers, strings) and dynamic ones (variables, function calls). It is the dynamic ones that obviously have to be interpreted in context. The class Context provides a context for interpreting Values.

All the jess.Value member functions, like intValue(jess.Context), that accept a jess.Context as an argument are self-resolving; that is, if a jess.Value object represents a function call, the call will be executed in the given jess.Context, and the intValue() method will be called on the result. Therefore, you often don't need to worry about resolution as it is done automatically. There are several cases where you will, however.

If you try to convert random values by creating a Value and retrieving it as some other type, you'll generally get a JessException. However, some types can be freely interconverted: for example, integers and floats.

(C) 2013 Sandia Corporation

See Also:
Serialized Form

Constructor Summary
Value(boolean b)
          Contruct a boolean value object (one of the RU.SYMBOLs "TRUE" or "FALSE".)
Value(double d, int type)
          Contruct a value of floating-point type.
Value(int value, int type)
          Contruct a value of integral type.
Value(java.lang.Object o)
          Contruct a value of Java object type.
Value(java.lang.String s, int type)
          Contruct a value of String type.
Value(Userfunction function)
          Contruct a value of lambda type.
Value(Value v)
          Contruct a value that is a copy of another Value.
Value(ValueVector f, int type)
          Contruct a value of list type.
 
Method Summary
 java.lang.String atomValue(Context c)
          Deprecated. use symbolValue instead
 boolean equals(java.lang.Object v)
          Compare this value to another object.
 boolean equals(Value v)
          Compare this value to another value.
 boolean equalsStar(Value v)
          Like equals(Value), but returns true for 3 == 3.0
 java.lang.Object externalAddressValue(Context c)
          Deprecated. As of Jess 7, use javaObjectValue(Context) instead.
 Fact factValue(Context c)
          Returns the contents of this value, as a fact.
 double floatValue(Context c)
          Returns the contents of this value, as a double.
 Funcall funcallValue(Context c)
          Returns the contents of this value, as a function call.
 Userfunction functionValue(Context c)
          Return the value of this object as a Userfunction.
 int hashCode()
          Return a hashcode for the object.
 int intValue(Context c)
          Returns the contents of this value, as an int.
 boolean isLexeme(Context c)
          Indicate whether this object represents a lexeme.
 boolean isLiteral()
          Indicate whether this value represents a literal.
 boolean isNumeric(Context c)
          Indicate whether this object represents a number.
 boolean isVariable()
          Indicate whether this is a variable.
 java.lang.Object javaObjectValue(Context c)
          Returns the contents of this value, as a Java object.
 ValueVector listValue(Context c)
          Returns the contents of this value, as a list.
 long longValue(Context c)
          Returns the contents of this value, as a long.
 double numericValue(Context c)
          Returns the contents of this value, as a number.
 Value resolveValue(Context c)
          Given an evaluation context, return the "true value" of this Value.
 java.lang.String stringValue(Context c)
          Returns the contents of this value, as a String.
 java.lang.String symbolValue(Context c)
          Returns the contents of this value, as a symbol.
 java.lang.String toString()
          Return a pretty-print version of this value, without adding parens to any lists.
 java.lang.String toStringWithParens()
          Return a pretty-print version of this value, adding parens to any lists.
 int type()
          Return the type of this variable.
 java.lang.String variableValue(Context c)
          Returns the contents of this value, as a String (a variable name).
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Value

public Value(int value,
             int type)
      throws JessException
Contruct a value of integral type. Allowed type values are RU.NONE and RU.INTEGER.

Parameters:
value - the value
type - the type
Throws:
JessException - if the value and type don't match.

Value

public Value(Value v)
Contruct a value that is a copy of another Value.

Parameters:
v - the Value to copy

Value

public Value(java.lang.String s,
             int type)
      throws JessException
Contruct a value of String type. Allowed type values are RU.SYMBOL, RU.STRING, RU.SLOT and RU.MULTISLOT.

Parameters:
s - the value
type - the type
Throws:
JessException - if the value and type don't match.

Value

public Value(ValueVector f,
             int type)
      throws JessException
Contruct a value of list type. Only allowed type value is RU.LIST.

Parameters:
f - the value
type - the type
Throws:
JessException - if the value and type don't match.

Value

public Value(double d,
             int type)
      throws JessException
Contruct a value of floating-point type. Allowed type values are RU.FLOAT, RU.LONG, and RU.INTEGER.

Parameters:
d - the value
type - the type
Throws:
JessException - if the value and type don't match.

Value

public Value(boolean b)
Contruct a boolean value object (one of the RU.SYMBOLs "TRUE" or "FALSE".)

Parameters:
b - the value

Value

public Value(java.lang.Object o)
Contruct a value of Java object type.

Parameters:
o - the value -- any Java object

Value

public Value(Userfunction function)
Contruct a value of lambda type.

Parameters:
function - a Deffunction
Method Detail

externalAddressValue

public java.lang.Object externalAddressValue(Context c)
                                      throws JessException
Deprecated. As of Jess 7, use javaObjectValue(Context) instead.

Returns the contents of this value, as a Java object.

Parameters:
c - the execution context used to resolve the value
Returns:
the Java object
Throws:
JessException - if this value does not contain a Java object

javaObjectValue

public java.lang.Object javaObjectValue(Context c)
                                 throws JessException
Returns the contents of this value, as a Java object.

Parameters:
c - the execution context used to resolve the value
Returns:
the Java object
Throws:
JessException - if this value does not contain a Java object

funcallValue

public Funcall funcallValue(Context c)
                     throws JessException
Returns the contents of this value, as a function call.

Parameters:
c - the execution context used to resolve the value
Returns:
the function call object
Throws:
JessException - if this value does not contain a function call.

factValue

public Fact factValue(Context c)
               throws JessException
Returns the contents of this value, as a fact.

Parameters:
c - the execution context used to resolve the value
Returns:
the fact
Throws:
JessException - if this value does not contain a fact

listValue

public ValueVector listValue(Context c)
                      throws JessException
Returns the contents of this value, as a list.

Parameters:
c - the execution context used to resolve the value
Returns:
the list
Throws:
JessException - if this value does not contain a list
JessException - if something goes wrong during value resolution

numericValue

public double numericValue(Context c)
                    throws JessException
Returns the contents of this value, as a number.

Parameters:
c - the execution context used to resolve the value
Returns:
the number as a double
Throws:
JessException - if this value does not contain any kind of number

intValue

public int intValue(Context c)
             throws JessException
Returns the contents of this value, as an int.

Parameters:
c - the execution context used to resolve the value
Returns:
the number as an int
Throws:
JessException - if this value does not contain any kind of number

longValue

public long longValue(Context c)
               throws JessException
Returns the contents of this value, as a long.

Parameters:
c - the execution context used to resolve the value
Returns:
the number as a long
Throws:
JessException - if this value does not contain any kind of number.

floatValue

public double floatValue(Context c)
                  throws JessException
Returns the contents of this value, as a double.

Parameters:
c - the execution context used to resolve the value
Returns:
the number as a double
Throws:
JessException - if this value does not contain any kind of number.

atomValue

public final java.lang.String atomValue(Context c)
                                 throws JessException
Deprecated. use symbolValue instead

Returns the contents of this value, as a symbol.

Parameters:
c - the execution context used to resolve the value
Returns:
the symbol
Throws:
JessException - if this value does not contain any kind of String.

symbolValue

public java.lang.String symbolValue(Context c)
                             throws JessException
Returns the contents of this value, as a symbol.

Parameters:
c - the execution context used to resolve the value
Returns:
the symbol
Throws:
JessException - if this value does not contain any kind of String

variableValue

public java.lang.String variableValue(Context c)
                               throws JessException
Returns the contents of this value, as a String (a variable name).

Parameters:
c - the execution context used to resolve the value
Returns:
the name of the variable
Throws:
JessException - if this value does not contain a variable.

stringValue

public java.lang.String stringValue(Context c)
                             throws JessException
Returns the contents of this value, as a String.

Parameters:
c - the execution context used to resolve the value
Returns:
the string
Throws:
JessException - if this value does not contain any kind of String.

functionValue

public Userfunction functionValue(Context c)
                           throws JessException
Return the value of this object as a Userfunction. If this object is a lexeme, try to interpret it as the name of a function. If it's a lambda value, then return the lambda.

Parameters:
c - the execution context used to resolve the value
Returns:
the Userfunction this value represents
Throws:
JessException - if this is not a function

toString

public java.lang.String toString()
Return a pretty-print version of this value, without adding parens to any lists.

Overrides:
toString in class java.lang.Object
Returns:
the formatted string

toStringWithParens

public java.lang.String toStringWithParens()
Return a pretty-print version of this value, adding parens to any lists.

Returns:
the formatted string

type

public int type()
Return the type of this variable. Always one of the constants in RU.

Returns:
the type

equals

public boolean equals(java.lang.Object v)
Compare this value to another object. As a convenience, if the parameter is not a Value, it will be compared to any contained Object inside this Value (a String or Java object.)

Overrides:
equals in class java.lang.Object
Parameters:
v - the object to compare to.
Returns:
true if the objects are equivalent.

equals

public boolean equals(Value v)
Compare this value to another value. Believe it or not, using this separate overloaded routine has a measurable impact on performance - since so much time is spent comparing Values.

Parameters:
v - the Value to compare to.
Returns:
true if the Values are equivalent.

equalsStar

public boolean equalsStar(Value v)
Like equals(Value), but returns true for 3 == 3.0

Parameters:
v - Value to compare to
Returns:
true if the values are loosely equivalent

hashCode

public int hashCode()
Return a hashcode for the object.

Overrides:
hashCode in class java.lang.Object
Returns:
the hashcode

resolveValue

public Value resolveValue(Context c)
                   throws JessException
Given an evaluation context, return the "true value" of this Value. For this class, the true value is always "this". For subclasses, the Context may be used to compute a new Value.

Parameters:
c - An execution context. You can pass null if you are sure that you're not calling this method on a subclass that uses the argument.
Returns:
this object
Throws:
JessException - if something goes wrong during value resolution
See Also:
Variable, Funcall

isNumeric

public boolean isNumeric(Context c)
                  throws JessException
Indicate whether this object represents a number. This includes FLOAT, INTEGER, LONG, and FACT values, as well as Strings and symbols that could be parsed as an INTEGER, LONG, or FLOAT.

Parameters:
c - the execution context used to resolve the value
Returns:
true if this Value is a number.
Throws:
JessException - if something goes wrong during value resolution

isLexeme

public boolean isLexeme(Context c)
                 throws JessException
Indicate whether this object represents a lexeme. This includes Strings and symbols.

Parameters:
c - the execution context used to resolve the value
Returns:
true if this Value is a lexeme
Throws:
JessException - if something goes wrong during value resolution

isLiteral

public boolean isLiteral()
Indicate whether this value represents a literal. A literal has type STRING, SYMBOL, INTEGER, FLOAT, or LONG, and is not a variable.

Returns:

isVariable

public boolean isVariable()
Indicate whether this is a variable.

Returns:
true if the type is VARIABLE or MULTIVARIABLE

2013 Sandia Corporation