The BooleanEval Component

The BooleanEval component provides a convenience API for evaluating boolean expressions in xADL documents. The BooleanEval component provides 2 functions specified by IBooleanEval:

The eval method is responsible for evaluating a boolean expression based on the symbol table passed in. For more information on the symbol table, go here. If a variable in the expression is not defined (no value in the symbol table), it will evaluate the expression as much as possible (taking advantage of short-circuiting). Its Javadoc is shown here:

eval

public ObjRef eval( ObjRef exp, SymbolTable symTable)
	throws MissingElementException, NoSuchTypeException,
	TypeMismatchException;

This function will evaluate the boolean expression passed in and will attempt to evaluate based on the symbol table passed in. The expression is also cloned so the original expression passed in is left unchanged. The boolean expression must be part of an xArch document and must have a parent with the expression as "BooleanExp"

Note: It will ignore case when evaluating strings.

Parameters:

exp - The ObjRef pointing to the boolean expression that needs to be evaluated.
symTable - This is the table that contains all the variables and their values.

Returns: ObjRef pointing to a modified version of the cloned expression. This boolean expression can only be TRUE, FALSE, or a pruned version of the cloned expression if the not all variables can be resolved.

Exceptions:

MissingElementException - This exception is thrown when the evaluator cannot find a required element in the expression.
NoSuchTypeException - This exception is thrown when it encounters an unknown/invalid type when evaluating.
TypeMismatchException - This exception is thrown when the type of the operands do not match during an evaluation.

A call to this function looks like this:

/* Obtain a reference to the boolean eval component...  */
IBooleanEval boolEval = /* get reference here */ ;
ObjRef result = boolEval.eval( boolExp, symTab );

For example, if the symbol table contained:

a = 1
b = 2

The the following expressions would return expressions containing:

b >= a --> TRUE
a == 1 && z > 0 --> z > 0
a != 1 && z > 0 --> FALSE
a == 1 || z > 0 --> TRUE
a != 1 || z > 0 --> z > 0

The boolValue method provides a simple way to extract the boolean value of a boolean value represented by an ObjRef (ie. ObjRef to an IBool). Its Javadoc is shown here:

boolValue

public boolean boolValue( ObjRef bool )
            throws MissingElementException, TypeMismatchException;

This function takes in a bool reference and returns true or false.

Parameters:

bool - The Bool INSIDE a boolean expression

Returns: Boolean containing the value of the bool (true/false)

Exceptions:

MissingElementException - This exception is thrown if the element pointed by the bool does not have a "value" field or is null
TypeMismatchException - This exception is thrown if the element pointed by the bool is not a boolean expression

This function is can be used to determine the results of the evaluation:

IBooleanEval boolEval = /* get reference here */ ;
ObjRef result = boolEval.eval( boolExp, symTab );

ObjRef bool = ( ObjRef )xArch.get( result, "Bool" );

// check to see if it could be evaluated
if (bool != null) {
    if (boolEval.boolValue(bool) {
        ...
    }
    else {
        ...
    }
}
// partial eval
else {
    ...
}

Additional questions about the BooleanEval should be sent to Ping H. Chen.