ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.able.rules
Class AbleInferenceEngine

java.lang.Object
  |
  +--com.ibm.able.rules.AbleInferenceEngine
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbleBackwardChainInferenceEngine, AbleForwardChainInferenceEngine, AbleFuzzyInferenceEngine, AbleMutExEngine, AblePatternMatchEngine, AblePatternMatchLiteEngine, AblePredicateEngine, AbleScriptEngine, PluggableEngine

public abstract class AbleInferenceEngine
extends java.lang.Object
implements java.io.Serializable

This class is an abstract base class for all inference engines used by an AbleRuleSet. An inference engine provides the control code and inferencing algorithms for processing a ruleblock (consisting of one or more rules and an optional working memory) in an Able ruleset.

One function performed by an inference engine is to validate the rules in the associated ruleblock to insure they are are of the appropriate type and contain the correct elements to be processed by the inference engine.

The major processing method is infer() which is called by the AbleRuleSet bean as part of the normal bean process() method.

Instances of this class are not directly constructed by the user but are dynamically created by the AbleRuleBlock init() method.

See Also:
AbleRuleSet, AbleRuleBlock, AbleRule, Serialized Form

Field Summary
protected  int myDebugLevel
          The debug level for this inference engine (passed through from RuleSet)
protected  AbleRuleBlock myRuleBlock
          myRuleBlock is the ruleblock whose rules are used for inferencing
protected  AbleRuleSet myRuleSet
          myRuleSet is the ruleset providing the context for this inference engine
protected  int myRulesFiredCount
          The number of rules fired during the last infer() call Note: this value is reset on each infer() call
protected  AbleLogger myTracer
          myTracer may be null, but if present, allows the inference engine to trace its evaluation steps.
protected  AbleWorkingMemory myWorkingMemory
           
 
Constructor Summary
AbleInferenceEngine()
          Create a new base inference engine.
AbleInferenceEngine(AbleLogger theTracer)
          Create a new base inference engine.
AbleInferenceEngine(AbleRuleSet theRuleSet, AbleLogger theTracer)
          Create a new base inference engine over the specified ruleset.
AbleInferenceEngine(AbleRuleSet theRuleSet, AbleLogger theTracer, AbleRuleBlock theRuleBlock)
          Create a new base inference engine over the specified ruleset.
 
Method Summary
 void askUser(AbleVariable theVariable)
          If the askUser() UDF has been defined, prompt a user to provide a value for specific variable during backward inferencing.
protected static boolean conditionalRulesValid(AbleRuleSet ruleSet, AbleRuleBlock theRuleBlock)
          Make sure the conditional rules in a ruleblock are "executable".
static java.lang.String Copyright()
          Determine the copyright of this class.
static java.lang.Boolean evalAntecedentClause(AbleAntecedentClause theClause)
          Evaluate the specified antecedent clause and update the clause with a new truth value.
static java.lang.Boolean evalAntecedentExpression(AbleExpression theExpression)
          Evaluate the specified antecedent expression
protected  void evalAssertionClause(AbleAssertionClause theClause)
           
protected  void evalAssertionRule(AbleAssertionRule theRule)
           
protected  void evalConditionalRule(AbleConditionalRule theRule)
          Evaluate a conditional (if-then) rule.
protected  void evalConsequentClause(AbleConsequentClause theClause)
          Evaluate the specified consequent clause.
protected  void evalDoUntilRule(AbleDoUntilRule theRule)
          Evaluate a do-until rule.
protected  void evalDoWhileRule(AbleDoWhileRule theRule)
          Evaluate a do-while rule.
protected  void evalForLoopRule(AbleForLoopRule theRule)
          Evaluate a for-loop rule.
protected  void evalIfThenElseRule(AbleIfThenElseRule theRule)
          Evaluate an if (expr) then-else rule.
protected  void evalPatternMatchRule(AblePatternMatchRule theRule)
          Evaluate a pattern-match (when-do) rule.
protected  void evaluateDoActions(AbleRule theRule)
           
protected  void evalWhileDoRule(AbleWhileDoRule theRule)
          Evaluate a while-do rule.
protected  void fireEngineBreakpoint()
          Call out to the DebugLib to handle an Inference Engine breakpoint
protected  void firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
          Fire a property change through the ruleset object
abstract  java.lang.Object getControlParameter(java.lang.String theControlParameter)
          Returns the specified control parameter on the associated inference engine.
 AbleRuleSet getRuleSet()
          Retrieve a reference to the current ruleset.
 int getRulesFiredCount()
          Returns the number of rules fired during the last infer() call
 AbleWorkingMemory getWorkingMemory()
          Retrieve the workingMemory object (may be null).
abstract  void infer(AbleRuleBlock theRuleBlock)
          Inference over the set of rules in the specified ruleblock object.
 void init()
          Initialize the inference engine
abstract  boolean isRuleBlockValid(AbleRuleBlock theRuleBlock)
          Make sure the current ruleblock is "executable" when examined from a static viewpoint.
protected  void processAssertions(AbleRuleBlock theRuleBlock)
          Fire all enabled assertion rules.
protected  void processConsequent(AbleConditionalRule theRule)
          Evaluate the specified rule's consequent clauses and update the rule with a new truth value.
 void processRuleBlock(AbleRuleBlock theRuleBlock)
          Fire all rules in the specified rule block in sequential order.
 void resetRuleSet()
          Reset the current ruleset for another round of inferencing.
abstract  void setControlParameter(java.lang.String theControlParameter, java.lang.Object theValue)
          Set the specified control parameter on the associated inference engine.
 void setControlParameters(java.util.Hashtable theControlParameters)
          Set the (possibly empty) set of control parameters passed to the associated inference engine.
 void setDebugLevel(int theDebugLevel)
           
 void setRuleSet(AbleRuleSet theRuleSet)
          Set the ruleset over which inferencing will take place.
 void setWorkingMemory(AbleWorkingMemory theWorkingMemory)
          Set the workingMemory object to the specified value.
protected  void startDebugConsole()
          Call out to the DebugLib to start the Debug console
protected  void stopDebugConsole()
          Call out to the DebugLib to stop the Debug console and end debugging.
 java.lang.String toString()
          Returns a string containing the describing the engine.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

myRuleSet

protected AbleRuleSet myRuleSet
myRuleSet is the ruleset providing the context for this inference engine

myTracer

protected AbleLogger myTracer
myTracer may be null, but if present, allows the inference engine to trace its evaluation steps.

myRuleBlock

protected AbleRuleBlock myRuleBlock
myRuleBlock is the ruleblock whose rules are used for inferencing

myDebugLevel

protected int myDebugLevel
The debug level for this inference engine (passed through from RuleSet)

myWorkingMemory

protected AbleWorkingMemory myWorkingMemory

myRulesFiredCount

protected int myRulesFiredCount
The number of rules fired during the last infer() call Note: this value is reset on each infer() call
Constructor Detail

AbleInferenceEngine

public AbleInferenceEngine(AbleRuleSet theRuleSet,
                           AbleLogger theTracer,
                           AbleRuleBlock theRuleBlock)
Create a new base inference engine over the specified ruleset.
Parameters:
theRuleSet - A ruleset whose rules are to be used for inferencing by this inference engine.

theTracer - A tracer object to which this inference engine can log information. This may be null, in which case no information is logged.


AbleInferenceEngine

public AbleInferenceEngine(AbleRuleSet theRuleSet,
                           AbleLogger theTracer)
Create a new base inference engine over the specified ruleset.
Parameters:
theRuleSet - A ruleset whose rules are to be used for inferencing by this inference engine.

theTracer - A tracer object to which this inference engine can log information. This may be null, in which case no information is logged.


AbleInferenceEngine

public AbleInferenceEngine(AbleLogger theTracer)
Create a new base inference engine. The ruleset must be specified before the inference() method is called.
Parameters:
theTracer - A tracer object to which this inference engine can log information. This may be null, in which case no information is logged.


AbleInferenceEngine

public AbleInferenceEngine()
Create a new base inference engine. The ruleset must be specified before the inference() method is called.
Method Detail

setRuleSet

public final void setRuleSet(AbleRuleSet theRuleSet)
Set the ruleset over which inferencing will take place.
Parameters:
theRuleSet - A ruleset that replaces the current ruleset, if there is one.


getRuleSet

public final AbleRuleSet getRuleSet()
Retrieve a reference to the current ruleset.
Returns:
The current ruleset object.

resetRuleSet

public void resetRuleSet()
                  throws AbleException
Reset the current ruleset for another round of inferencing.

setControlParameters

public void setControlParameters(java.util.Hashtable theControlParameters)
                          throws AbleDataException
Set the (possibly empty) set of control parameters passed to the associated inference engine. Iterates over all key-value pairs
See Also:
setControlParameter(java.lang.String, java.lang.Object)

setControlParameter

public abstract void setControlParameter(java.lang.String theControlParameter,
                                         java.lang.Object theValue)
                                  throws AbleDataException
Set the specified control parameter on the associated inference engine. The target engine validates both the parameter name and value.

getControlParameter

public abstract java.lang.Object getControlParameter(java.lang.String theControlParameter)
                                              throws AbleDataException
Returns the specified control parameter on the associated inference engine. The target engine validates both the parameter name.

isRuleBlockValid

public abstract boolean isRuleBlockValid(AbleRuleBlock theRuleBlock)
                                  throws AbleDataException
Make sure the current ruleblock is "executable" when examined from a static viewpoint. Certain invalid configurations cannot be detected via static analysis of the rule objects. If validation fails, the inference engine must call myRuleSet.addIsExReason(java.lang.String) to set the reason.
Returns:
true, if the ruleblock is OK; false, if the ruleblock is not executable.

conditionalRulesValid

protected static boolean conditionalRulesValid(AbleRuleSet ruleSet,
                                               AbleRuleBlock theRuleBlock)
Make sure the conditional rules in a ruleblock are "executable". If validation fails, the reason is set via myRuleSet.addIsExReason(java.lang.String) and false is returned.
Returns:
true, if the ruleset is OK; false, if the ruleset is not executable.

init

public void init()
          throws AbleException
Initialize the inference engine

infer

public abstract void infer(AbleRuleBlock theRuleBlock)
                    throws AbleDataException
Inference over the set of rules in the specified ruleblock object.
Parameters:
theRuleBlock - The ruleblock to be processed by the engine.


processRuleBlock

public void processRuleBlock(AbleRuleBlock theRuleBlock)
                      throws AbleDataException
Fire all rules in the specified rule block in sequential order.

This method is called from a ruleset's invokeRuleBlock() method, and that method is called when a rule that uses the built-in invokeRuleBlock("name") call literal is evaluated.

Parameters:
theRuleBlock - The rule block from which rules are to be processed.

Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

processAssertions

protected void processAssertions(AbleRuleBlock theRuleBlock)
                          throws AbleDataException
Fire all enabled assertion rules.

For assertions, the evaluation must result in an assignment from the right-hand side to the left-hand side. Any other operation (such as a comparison) is meaningless and results in an exception.

Parameters:
theRuleBlock - The rule block from which rules are to be processed.

Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalAssertionRule

protected void evalAssertionRule(AbleAssertionRule theRule)
                          throws AbleDataException

evalConditionalRule

protected void evalConditionalRule(AbleConditionalRule theRule)
                            throws AbleDataException
Evaluate a conditional (if-then) rule.

Procesing is as follows:

  • Evaluate each antecedent.
  • If the value of an antecedent clause is null or false, any remaining antecedents are ignored, and the rule does not fire.
  • When all antecedents are true, the consequent is evaluated.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalIfThenElseRule

protected void evalIfThenElseRule(AbleIfThenElseRule theRule)
                           throws AbleDataException
Evaluate an if (expr) then-else rule.

Procesing is as follows:

  • Evaluate the antecedent expression.
  • If the value of the antecedent expression is null or false, the rule does not fire.
  • If the antecedent expresion evaluate to true, the consequent(s) are evaluated.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalPatternMatchRule

protected void evalPatternMatchRule(AblePatternMatchRule theRule)
                             throws AbleDataException
Evaluate a pattern-match (when-do) rule.

Procesing is as follows:

  • Evaluate the pattern match clause.
  • If the match returns any bindings the rule is triggered.
  • If the rule is triggered, it is fired with each valid binding.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalWhileDoRule

protected void evalWhileDoRule(AbleWhileDoRule theRule)
                        throws AbleDataException
Evaluate a while-do rule.

Procesing is as follows:

  • Evaluate each antecedent.
  • If the value of an antecedent clause is null or false, any remaining antecedents are ignored, and the rule does not fire.
  • When all antecedents are true, the consequent is evaluated.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalDoWhileRule

protected void evalDoWhileRule(AbleDoWhileRule theRule)
                        throws AbleDataException
Evaluate a do-while rule.

Procesing is as follows:

  • Evaluate the actions in the body of the rule.
  • Repeat until the test expression evaluates to false.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalDoUntilRule

protected void evalDoUntilRule(AbleDoUntilRule theRule)
                        throws AbleDataException
Evaluate a do-until rule.

Procesing is as follows:

  • Evaluate the actions in the body of the rule.
  • Repeat until the test expression evaluates to true.
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalForLoopRule

protected void evalForLoopRule(AbleForLoopRule theRule)
                        throws AbleDataException
Evaluate a for-loop rule.

Procesing is as follows:

  • Evaluate each initializer expression.
  • Evaluate the test expression
  • if true, evaluate the actions in the body of the rule
  • Evaluate the iterator expressions. Go back and evaluate the test expression
Throws:
AbleDataException - when the data types are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evaluateDoActions

protected void evaluateDoActions(AbleRule theRule)
                          throws AbleDataException

evalAssertionClause

protected void evalAssertionClause(AbleAssertionClause theClause)
                            throws AbleDataException

evalAntecedentClause

public static java.lang.Boolean evalAntecedentClause(AbleAntecedentClause theClause)
                                              throws AbleDataException
Evaluate the specified antecedent clause and update the clause with a new truth value.
Parameters:
theClause - an antecedent clause to evaluate.

Returns:
the tri-valued result of the evaluation: true, if the clause evaluates to true; false, if the clause evaluates to false; or null, if the truth value is unknown or cannot be determined.
Throws:
AbleDataException - when the clause's data objects are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalAntecedentExpression

public static java.lang.Boolean evalAntecedentExpression(AbleExpression theExpression)
                                                  throws AbleDataException
Evaluate the specified antecedent expression
Parameters:
theExpression - an antecedent expression to evaluate.

Returns:
the tri-valued result of the evaluation: true, if the expression evaluates to true; false, if the expression evaluates to false; or null, if the truth value is unknown or cannot be determined.
Throws:
AbleDataException - when the expression's data objects are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

processConsequent

protected void processConsequent(AbleConditionalRule theRule)
                          throws AbleDataException
Evaluate the specified rule's consequent clauses and update the rule with a new truth value.
Parameters:
theRule - a rule whose consequent clauses are to be evaluated.

Throws:
AbleDataException - when the clause's data objects are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

evalConsequentClause

protected void evalConsequentClause(AbleConsequentClause theClause)
                             throws AbleDataException
Evaluate the specified consequent clause.
Parameters:
theClause - a consequent clause to evaluate.

Throws:
AbleDataException - when the clause's data objects are incompatible, or when the relational operator is invalid for the current situation or unrecognized.

setDebugLevel

public final void setDebugLevel(int theDebugLevel)

firePropertyChange

protected void firePropertyChange(java.lang.String propertyName,
                                  java.lang.Object oldValue,
                                  java.lang.Object newValue)
Fire a property change through the ruleset object
Parameters:
propertyName - A String name of the property that changed
oldValue - The Object representing the old value
newValue - The Object representing the new value

fireEngineBreakpoint

protected void fireEngineBreakpoint()
                             throws AbleDataException
Call out to the DebugLib to handle an Inference Engine breakpoint

startDebugConsole

protected void startDebugConsole()
Call out to the DebugLib to start the Debug console

stopDebugConsole

protected void stopDebugConsole()
Call out to the DebugLib to stop the Debug console and end debugging.

This method is called at the end of each infer() cycle to cleanup the debugger. There may not be one, so any error is perfectly normal: don't log anything!


askUser

public void askUser(AbleVariable theVariable)
If the askUser() UDF has been defined, prompt a user to provide a value for specific variable during backward inferencing. If the user cancels out of the dialog, the variable's value is set to null.

If askUser() as not been defined, then set the variable value to null.

Parameters:
theVariable - a variable whose value cannot be determined any other way.


getRulesFiredCount

public int getRulesFiredCount()
Returns the number of rules fired during the last infer() call

setWorkingMemory

public void setWorkingMemory(AbleWorkingMemory theWorkingMemory)
Set the workingMemory object to the specified value.
Parameters:
theWorkingMemory - The working memory.


getWorkingMemory

public final AbleWorkingMemory getWorkingMemory()
Retrieve the workingMemory object (may be null).
Returns:
The current working memory, or null if no working memory exists.

toString

public java.lang.String toString()
Returns a string containing the describing the engine. For example, com.ibm.able.rules.AbleFuzzyInferenceEngine.
Overrides:
toString in class java.lang.Object
Returns:
The class name qualified with the package.

Copyright

public static java.lang.String Copyright()
Determine the copyright of this class.
Returns:
A String containing this class's copyright statement.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003