biz.chitec.quarterback.util.logic
Interface LogicExpr

All Superinterfaces:

java.lang.Cloneable

All Known Implementing Classes:

AlgebraicExpr, ArithmeticExpr, BetweenExpr, ConstantExpr, ContainsExpr, DynamicMenuBar.SimpleExpr, EqualsExpr, EvaluatorExpr, FilterExpr, InExpr, LikeExpr, NOTExpr, SmartCompareExpr

public interface LogicExpr

extends java.lang.Cloneable

Interface for logic expressions.

Logic expressions can serve for two purposes:

• In a given universe of constants, a logic expression can be evaluated to be either true or false.
• In a given universe of constants, all those constants can be picked which render a logic expression to be true.

This logic expression definition can be used for both usage types.

Evaluation as true or false

Logic expressions are used to deliver a boolean value to say whether a certain expression is true or false in a given universe of Objects. Normally, this universe will be a Map containing key-value pairs and the expressions reasoning about these values.

Example: We have the following program:

 Map m=new HashMap;m.put("X",new Integer(5));
 Map n=new HashMap;n.put("X",new Integer(6));
 LogicExpr le=new EqualsExpr("X",new Integer(6));
 boolean bm=le.evaluate(m);
 boolean bn=le.evaluate(n);
 

In this example, bm will be false while bn will be true.

The whole concept becomes increasingly interesting with logical expressions linking other logical expressions according to boolean algebra:

 LogicExpr german_chancellor_searcher=
   new ORExpr(
     new ANDExpr(
       new EqualsExpr("PRENAME","Helmut"),
       new ORExpr(
         new EqualsExpr("NAME","Schmidt"),
         new EqualsExpr("NAME","Kohl")
       )
     ),
     new ANDExpr(
       new EqualsExpr("PRENAME","Gerhard"),
       new EqualsExpr("NAME","Schroeder")
     )
   );
 
 Map p1=new HashMap();p1.put("NAME","Kohl");p1.put("PRENAME","Helmut");
 Map p2=new HashMap();p2.put("NAME","Beckenbauer");p2.put("PRENAME","Franz");
 Map p3=new HashMap();p3.put("NAME","Schroeder");p3.put("PRENAME","Gerhard");
 

Boolean evaluations are also important in database searches and there especially in the "where" part of select clauses. LogicExpr allows therefore to create an SQL-equivalent of the defined expression. This can be used in the where-part of a select clause. The whole mechanism follows an implicit "column-to-map-entry"-paradigm. If you suppose that each column of an SQL query is stored in certain Map fields (and each row of the query result is put in its own Map), then you can either apply the logical expression to the Map being the result of the query or its SQL-equivalent already to the query itself.

Element selection

Boolean evaluations as described above do already feature a "hidden" element selection, as the true/false decision picks a subset of the table as result set. Handling queries this way, however, restricts the database handling to those cases which are handleable by single SQL queries.

To overcome this restriction, we go one step further. We define the primary index of a certain database table as the above mentioned universe of constants. The logic expressions are describing database queries which have lists of such primary indexes as result. Having such lists, logical operations can be expressed as boolean algebra combining the lists after set theory.

AND and OR operation are simple intersection and unification operations of result sets. NOT, however, needs the complete universe to perform a rest operation. Archieving the complete universe can be a time-consuming task, therefore we define a sub-interface which delivers the universe.

As LogicExpr objects can be passed through GJSA connections, they can be used quite well as a general querying mechanism between clients and servers in the GJSA framework.

Version:

$Id: 4f531a536f85bd36bb2643477bf770ed37361fa4 $

Author:

chitec/Dirk Hillbrecht 2001, cantamen/Dirk Hillbrecht 2004,2005. Distributed under the terms of the GNU LGPL.

Nested Class Summary

static interface	LogicExpr.Converter Special interface for value conversion.
static interface	LogicExpr.UniverseGenerator Special interface for universe generation.

Method Summary

java.lang.Object	clone() Deep-copy the logic expression.
void	convertValues(LogicExpr.Converter c) Conversion of values in the expressions (e.g. for replacing external representations of database entries with their internal key)
boolean	evaluate(java.lang.Object universe) Is the expression valid in the given universe
java.lang.Object[]	getInternalVars() Only for GJSA class parsers: get class variables to create object from a parsed string.
int[]	getResultSet(LogicExpr.UniverseGenerator generator) Return all elements of the universe which match the expression
boolean	isReady() Returns if the expression is actually evaluable, i.e. any of the evaluating methods can be called.
boolean	isTreeReady() Returns whether this and all deeper expressions are evaluable.
java.lang.String	sqlString(java.util.Map identifiers) Returns an SQL representation of the expression with the constant names replaced by the ones in the given Map.

Method Detail

isReady

public boolean isReady()

Returns if the expression is actually evaluable, i.e. any of the evaluating methods can be called. If this method returns false, the expression should not be evaluated. Note that this method does not care for the evaluation state of any potential children of this LogicExpr. Use isTreeEvaluable() for this test.

Returns:

True if an evaluation is possible, false if not.

isTreeReady

public boolean isTreeReady()

Returns whether this and all deeper expressions are evaluable. Walks through the the expression tree and returns only true if all expressions below are evaluable.

Returns:

True if this and all expressions below are evaluable, false otherwise.

evaluate

public boolean evaluate(java.lang.Object universe)

Is the expression valid in the given universe

getResultSet

public int[] getResultSet(LogicExpr.UniverseGenerator generator)

Return all elements of the universe which match the expression

sqlString

public java.lang.String sqlString(java.util.Map identifiers)

Returns an SQL representation of the expression with the constant names replaced by the ones in the given Map.

getInternalVars

public java.lang.Object[] getInternalVars()

Only for GJSA class parsers: get class variables to create object from a parsed string.

convertValues

public void convertValues(LogicExpr.Converter c)

Conversion of values in the expressions (e.g. for replacing external representations of database entries with their internal key)

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Deep-copy the logic expression. The contract for this method says the the logic expression must be deep-copied. I.e. if clone() is called for the root expression of a certain expression tree, a completely independent tree is returned.

Note: This method must be defined in a way that makes it quite complicated to call it for simply cloning a logic expression tree: It returns an Object (which always happens to be a LogicExpr) and it might throw a CloneNotSupportedException - which will (a) never happen and is (b) no RuntimeException, so a caller would always have to catch it.

To make life simpler, there is a static method LogicExprUtilties.cloneLogicExpr() which will call clone() on the root object and take care of return value and exceptions.

Returns:

Independent copy of the expression containing also copies of any subsequent expressions.

Throws:

java.lang.CloneNotSupportedException