jess
Class Value

java.lang.Object
  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.

• When interpreting arguments to a function written in Java. The parameters passed to a Java Userfunction may themselves represent function calls. It may be important, therefore, that these values be resolved only once, as these functions may have side-effects (I'm tempted to use the computer-science word: these functions may not be idempotent. Idempotent functions have no side-effects and thus may be called multiple times without harm.) You can accomplish this by calling one of the (x)Value() methods and storing the return value, using this return value instead of the parameter itseld. Alternatively, you may call resolveValue(Context) and store the return value in a new jess.Value variable, using this value as the new parameter. Note that the type() method will return RU.VARIABLE for a jess.Value object that refers to a variable, regardless of the type of the value the variable is bound to. The resolved value will return the proper type.

  Note that arguments to deffunctions are resolved automatically, before your Jess language code runs.

• when returning a jess.Value object from a function written in Java. If you return one of a function's parameters from a Java Userfunction, be sure to return the return value of resolveValue(), not the parameter itself.
• When storing a jess.Value object. It is important that any values passed out of a particular execution context be resolved; for example, before storing a Value object in a Map, resolveValue() should always be called on both the key and object.

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