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

com.ibm.able.rules
Class AbleRuleBlock

java.lang.Object
  |
  +--com.ibm.able.rules.AbleRuleBlock
All Implemented Interfaces:
java.io.Serializable

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

This class represents a named set of rules, an associated inference engine, and a return data type. Ruleblocks are used to partition rulesets into groups which are processed by an inference engine to produce some result.

There are several "special" ruleblocks with reserved names, such as init(), preProcess(), process(), postProcess(), handleTimerEvent(), handleAbleEvent(), catch(), and quitAll(). These ruleblocks are processed at specific times in the life of an AbleRuleSet bean.

Other named ruleblocks can be invoked using the invokeRuleBlock("name") built-in function. Ruleblocks can return no value (void) or they can return values to the caller using the returnFromRuleBlock(value) built-in function.

See Also:
Serialized Form

Field Summary
protected  java.util.Vector myAstRuleList
          myAstRuleList is the sequence of assertion rules in this rule block.
protected  java.util.Vector myCndRuleList
          myCndRuleList is the sequence of conditional rules in this rule block.
protected  java.lang.String myComment
          "myComment" provides a place to associate a comment with this rule block.
protected  java.util.Hashtable myControlParameterList
          The parameters used to control the associated inference engine
protected  java.util.Vector myControlParameters
           
protected  java.lang.String myEngineType
          The type of inference engine to be used to evaluate the rules in this ruleblock
protected  java.util.Vector myIfThenElseRuleList
          myIfThenElseRuleList is the sequence of if (expr) then-else rules in this rule block.
protected  AbleInferenceEngine myInferenceEngine
          The inference engine associated with this ruleblock
protected  java.util.Vector myIterationRuleList
          myIterationRuleList is the sequence of iteration rules in this rule block.
protected  java.lang.String myName
          myName is the unique name of this particular rule block; that is, each rule block within an AbleRuleSet must have a unique name.
protected  java.util.Vector myPatternMatchRuleList
          myPatternMatchRuleList is the sequence of pattern match rules in this rule block.
protected  java.util.Vector myPredicateRuleList
          myPredicateRuleList is the sequence of predicate facts and rules in this rule block.
protected  boolean myProcessedFlag
          myProcessedFlag indicates whether this rule block has been processed at least once.
protected  java.lang.String myReturnType
          The rule block return type (for example "String")
protected  java.lang.Object myReturnValue
          The return value from this ruleblock reset to null on entry, only set if user codes a return() statement
protected  java.util.Vector myRuleList
          myRuleList is the sequence of all rules that make up this rule block.
protected  AbleRuleSet myRuleSet
          The parent ruleset
protected  AbleLogger myTrace
          The inference engine trace logger
static java.lang.String RuleBlockCatch
          Rule Block Name: Catch
static java.lang.String RuleBlockInit
          Rule Block Name: Init
static java.lang.String RuleBlockPostProcess
          Rule Block Name: PostProcess
static java.lang.String RuleBlockPreProcess
          Rule Block Name: PreProcess
static java.lang.String RuleBlockProcess
          Rule Block Name: Process
static java.lang.String RuleBlockProcessAbleEvent
          Rule Block Name: ProcessAbleEvent
static java.lang.String RuleBlockProcessTimerEvent
          Rule Block Name: ProcessTimerEvent
static java.lang.String RuleBlockQuitAll
          Rule Block Name: QuitAll
 
Constructor Summary
AbleRuleBlock(java.lang.String theName, AbleRuleSet theRuleSet, AbleLogger theLogger, java.lang.String theReturnType)
          Create a new rule block with the specified name.
 
Method Summary
protected  void addAssertion(AbleAssertionRule theRule)
          Add an assertion to the rule block.
protected  void addConditionalRule(AbleConditionalRule theRule)
          Add a conditional (if-then) rule to the rule block.
protected  void addIfThenElseRule(AbleIfThenElseRule theRule)
          Add an if (expr) then-else rule to the rule block.
protected  void addIterationRule(AbleIterationRule theRule)
          Add an iteration rule (do/while, do/until, while/do, for-loop) to the rule block.
protected  void addPatternMatchRule(AblePatternMatchRule theRule)
          Add a pattern match (when-do) rule to the rule block.
protected  void addPredicateRule(AblePredicateRule theRule)
          Add a predicate fact or rule to the rule block.
protected  void addRule(AbleRule theRule)
          Add an Able rule (any type) to the end of the rule block.
 java.lang.String arlString()
          Return a formal Able Rule Language (ARL) String.
 void checkTimePeriodPreConditions(java.util.Calendar theCurrentTime)
          Evaluate each rule in the ruleblock against the time period preconditions.
static java.lang.String Copyright()
          Determine the copyright of this class.
 java.lang.String getArlComment()
          Retrieve the comment associated with this ruleblock as an arl string enclosed in javadoc delimeters.
 java.util.Vector getAssertions()
          Retrieve the list of assertion rules.
 java.lang.String getComment()
          Retrieve the comment associated with this ruleblock.
 java.util.Vector getConditionalRules()
          Retrieve the list of conditional rules.
 java.lang.Object getControlParameter(java.lang.String theControlParameter)
          Returns a single control parameter on the associated inference engine.
 java.util.Hashtable getControlParameters()
          Retrieve the (possibly empty) set of parameters passed to the associated inference engine.
 java.util.Vector getEnabledAssertions()
          Retrieve the list of enabled assertion rules.
 java.util.Vector getEnabledConditionalRules()
          Retrieve the list of enabled conditional rules.
 java.util.Vector getEnabledIfThenElseRules()
          Retrieve the list of enabled if-then-else rules.
 java.util.Vector getEnabledIterationRules()
          Retrieve the list of enabled iteration rules.
 java.util.Vector getEnabledPatternMatchRules()
          Retrieve the list of enabled pattern match rules.
 java.util.Vector getEnabledPredicateRules()
          Retrieve the list of enabled predicate facts and rules.
 java.util.Vector getEnabledRules()
          Retrieve the list of all enabled rules.
 java.lang.String getEngineType()
          Retrieve the current engine type.
 java.util.Vector getIfThenElseRules()
          Retrieve the list of if-then-else rules.
 AbleInferenceEngine getInferenceEngine()
          Retrieve the rule block's inference engine.
 java.util.Vector getIterationRules()
          Retrieve the list of iteration rules.
 java.lang.String getName()
          Retrieve the rule block's unique name.
 java.util.Vector getPatternMatchRules()
          Retrieve the list of pattern match rules.
 java.util.Vector getPredicateRules()
          Retrieve the list of predicate facts and rules.
 java.lang.String getReturnType()
          Retrieve the return data type of this ruleblock
 java.lang.Object getReturnValue()
          Retrieve the return value (if any) set on this ruleblock
 java.util.Vector getRules()
          Retrieve the list of all rules.
 int getRulesFiredCount()
          Returns the number of rules fired by the associated inference engine during the last infer() call
 java.util.Vector getRuleTemplates()
          Retrieve all rule template objects defined in this ruleblock
 java.lang.String getTemplateString(java.util.Vector theTemplateVars)
          Retrieve a text format string for use by ruleset templates.
 java.util.Vector getTemplateVars(AbleRuleSet theRuleSet)
          Return a list of template vars referenced by this ruleblock.
 AbleWorkingMemory getWorkingMemory()
          Retrieve the working memory associated with the rule block's inference engine.
 void init()
          Initialize and configure the ruleblock by dynamically creating an instance of the specified inference engine.
protected  void insertRuleAt(int theIndex, AbleRule theRule)
          Insert an Able rule (any type) at specified position in the rule block.
 boolean isProcessed()
          Determine whether this rule block has been processed at least once.
 void process()
           
protected  void removeRule(AbleRule theRule)
          Remove an Able rule (any type) from the rule block.
protected  void replaceRule(AbleRule theOldRule, AbleRule theNewRule)
          Replace an Able rule (any type) in the rule block at its current position in the ruleblock.
 void reset()
          Reset the rule block so that rules can be fired again: all rules are set to their original state.
 void setComment(java.lang.String theComment)
          Set (or change) the comment associated with this ruleblock.
 void setControlParameter(java.lang.String theControlParameter, java.lang.Object theValue)
          Set a single control parameter on the associated inference engine.
 void setControlParameters(java.util.Hashtable theControlParameters)
          Set the (possibly empty) set of parameters passed to the associated inference engine.
 void setDebugLevel(int theDebugLevel)
          Set the debug level on the associated inference engine
 void setEngineType(java.lang.String theEngineType)
          Set the type of the inference engine to be used by this ruleblock Note: the name must be registered with the AbleRuleSet and the engine class must be accessible via the CLASSPATH.
 void setProcessed(boolean theProcessedFlag)
          Set the flag that indicates whether this rule block has been processed at least once.
 void setReturnValue(java.lang.Object theReturnValue)
          Set the return value for this ruleblock
 java.lang.String toString()
          Retrieve a string describing (the contents of) the object.
 java.lang.String traceString(int theTraceStringFlavor)
          Retrieve a string describing (the contents of) the object.
 java.lang.String xmlString()
          Return a formal XML string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

RuleBlockInit

public static final java.lang.String RuleBlockInit
Rule Block Name: Init

The "init" rule block is processed once when the AbleRuleSet init() method is invoked.


RuleBlockProcess

public static final java.lang.String RuleBlockProcess
Rule Block Name: Process

The "process" rule block is meant to be processed multiple times, once for each "process" cycle, and it is meant to be processed by a specialized inference engine, such as a fuzzy logic inference engine or a bollean forward chainer. The rules are processed in an order determined by the inference engine.


RuleBlockPreProcess

public static final java.lang.String RuleBlockPreProcess
Rule Block Name: PreProcess

The "preProcess" rule block is meant to be called before the process() rule block is called.


RuleBlockPostProcess

public static final java.lang.String RuleBlockPostProcess
Rule Block Name: PostProcess

The "postProcess" rule block is meant to be processed each time processing of the process() rule block quiesces.


RuleBlockCatch

public static final java.lang.String RuleBlockCatch
Rule Block Name: Catch

The "catch" rule block is called to handle exceptions that are thrown during the evaluation of the process() method.


RuleBlockQuitAll

public static final java.lang.String RuleBlockQuitAll
Rule Block Name: QuitAll

The "finally" rule block is called when the bean quitAll() method is invoked.


RuleBlockProcessTimerEvent

public static final java.lang.String RuleBlockProcessTimerEvent
Rule Block Name: ProcessTimerEvent

The "processTimerEvent" rule block is called to process timer events generated by the ruleset bean.


RuleBlockProcessAbleEvent

public static final java.lang.String RuleBlockProcessAbleEvent
Rule Block Name: ProcessAbleEvent

The "processAbleEvent" rule block is called to process able events received by the ruleset bean due to a handleAbleEvent() (or processAbleEvent()) method invocation. The rules can access the event object via the "event" built-in variable.


myName

protected java.lang.String myName
myName is the unique name of this particular rule block; that is, each rule block within an AbleRuleSet must have a unique name.

myInferenceEngine

protected AbleInferenceEngine myInferenceEngine
The inference engine associated with this ruleblock

myRuleList

protected java.util.Vector myRuleList
myRuleList is the sequence of all rules that make up this rule block. The rules are in order of addition to this rule block.

myAstRuleList

protected java.util.Vector myAstRuleList
myAstRuleList is the sequence of assertion rules in this rule block. It is a subset of myRuleList.

myCndRuleList

protected java.util.Vector myCndRuleList
myCndRuleList is the sequence of conditional rules in this rule block. It is a subset of myRuleList.

myIfThenElseRuleList

protected java.util.Vector myIfThenElseRuleList
myIfThenElseRuleList is the sequence of if (expr) then-else rules in this rule block. It is a subset of myRuleList.

myPatternMatchRuleList

protected java.util.Vector myPatternMatchRuleList
myPatternMatchRuleList is the sequence of pattern match rules in this rule block. It is a subset of myRuleList.

myPredicateRuleList

protected java.util.Vector myPredicateRuleList
myPredicateRuleList is the sequence of predicate facts and rules in this rule block. It is a subset of myRuleList.

myIterationRuleList

protected java.util.Vector myIterationRuleList
myIterationRuleList is the sequence of iteration rules in this rule block. It is a subset of myRuleList.

myProcessedFlag

protected boolean myProcessedFlag
myProcessedFlag indicates whether this rule block has been processed at least once. The flag is initialized to false, but is not otherwise maintained by the rule block. The flag must be maintained by processing code, an inference engine, for example, that is interested in keeping track of whether a rule block might have been previously processed. This flag and its associated methods make it possible to implement an "init" type of rule block that is processed just once at initialization time.

This flag is not reset by the reset() method.


myEngineType

protected java.lang.String myEngineType
The type of inference engine to be used to evaluate the rules in this ruleblock

myRuleSet

protected AbleRuleSet myRuleSet
The parent ruleset

myTrace

protected AbleLogger myTrace
The inference engine trace logger

myControlParameterList

protected java.util.Hashtable myControlParameterList
The parameters used to control the associated inference engine

myControlParameters

protected java.util.Vector myControlParameters

myReturnType

protected java.lang.String myReturnType
The rule block return type (for example "String")

myReturnValue

protected java.lang.Object myReturnValue
The return value from this ruleblock reset to null on entry, only set if user codes a return() statement

myComment

protected java.lang.String myComment
"myComment" provides a place to associate a comment with this rule block. The value is initialized to the empty String ("") and is never expected to be null.
See Also:
setComment(String), getComment()
Constructor Detail

AbleRuleBlock

public AbleRuleBlock(java.lang.String theName,
                     AbleRuleSet theRuleSet,
                     AbleLogger theLogger,
                     java.lang.String theReturnType)
Create a new rule block with the specified name.
Parameters:
theName - The unique name of this rule block.

Method Detail

init

public void init()
          throws AbleException,
                 AbleParException,
                 AbleDataException
Initialize and configure the ruleblock by dynamically creating an instance of the specified inference engine.

process

public void process()
             throws AbleDataException

checkTimePeriodPreConditions

public final void checkTimePeriodPreConditions(java.util.Calendar theCurrentTime)
                                        throws AbleDataException
Evaluate each rule in the ruleblock against the time period preconditions. If the rule is active, make sure it is enabled.

setDebugLevel

public final void setDebugLevel(int theDebugLevel)
Set the debug level on the associated inference engine

getControlParameters

public java.util.Hashtable getControlParameters()
Retrieve the (possibly empty) set of parameters passed to the associated inference engine.

setControlParameters

public void setControlParameters(java.util.Hashtable theControlParameters)
                          throws AbleDataException
Set the (possibly empty) set of parameters passed to the associated inference engine.

setControlParameter

public void setControlParameter(java.lang.String theControlParameter,
                                java.lang.Object theValue)
                         throws AbleDataException
Set a single control parameter on the associated inference engine.

getControlParameter

public java.lang.Object getControlParameter(java.lang.String theControlParameter)
                                     throws AbleDataException
Returns a single control parameter on the associated inference engine.

setReturnValue

public void setReturnValue(java.lang.Object theReturnValue)
Set the return value for this ruleblock

getReturnValue

public java.lang.Object getReturnValue()
Retrieve the return value (if any) set on this ruleblock

getReturnType

public java.lang.String getReturnType()
Retrieve the return data type of this ruleblock

getName

public java.lang.String getName()
Retrieve the rule block's unique name.
Returns:
The unique name of the rule block.

setComment

public void setComment(java.lang.String theComment)
Set (or change) the comment associated with this ruleblock.
Parameters:
theComment - A String containing the new comment for this ruleblock. This comment replaces the current comment.

See Also:
myComment

getComment

public java.lang.String getComment()
Retrieve the comment associated with this ruleblock.
Returns:
A String containing the current comment associated with this ruleblock or the empty string if no comment has been set. The value is never expected to be null.
See Also:
myComment

getArlComment

public java.lang.String getArlComment()
Retrieve the comment associated with this ruleblock as an arl string enclosed in javadoc delimeters.
Returns:
A String containing the current comment associated with this ruleblock or the empty string if no comment has been set. The value is never expected to be null.
See Also:
myComment

getInferenceEngine

public AbleInferenceEngine getInferenceEngine()
Retrieve the rule block's inference engine.
Returns:
The inference engine of the rule block.

getWorkingMemory

public AbleWorkingMemory getWorkingMemory()
Retrieve the working memory associated with the rule block's inference engine.
Returns:
The working memory used by the inference engine of the rule block.

setEngineType

public void setEngineType(java.lang.String theEngineType)
Set the type of the inference engine to be used by this ruleblock Note: the name must be registered with the AbleRuleSet and the engine class must be accessible via the CLASSPATH.

getEngineType

public final java.lang.String getEngineType()
Retrieve the current engine type. Engine types are enumerated in the AbleRuleSet class.
Returns:
The current inference engine type.
See Also:
setEngineType(java.lang.String)

addAssertion

protected void addAssertion(AbleAssertionRule theRule)
Add an assertion to the rule block.
Parameters:
theRule - The assertion to add.


addConditionalRule

protected void addConditionalRule(AbleConditionalRule theRule)
Add a conditional (if-then) rule to the rule block.
Parameters:
theRule - The conditional rule to add.


addIfThenElseRule

protected void addIfThenElseRule(AbleIfThenElseRule theRule)
Add an if (expr) then-else rule to the rule block.
Parameters:
theRule - The if-then-else rule to add.


addPatternMatchRule

protected void addPatternMatchRule(AblePatternMatchRule theRule)
Add a pattern match (when-do) rule to the rule block.
Parameters:
theRule - The pattern match rule to add.


addPredicateRule

protected void addPredicateRule(AblePredicateRule theRule)
Add a predicate fact or rule to the rule block.
Parameters:
theRule - The predicate fact or rule to add.


addIterationRule

protected void addIterationRule(AbleIterationRule theRule)
Add an iteration rule (do/while, do/until, while/do, for-loop) to the rule block.
Parameters:
theRule - The rule to add.


addRule

protected void addRule(AbleRule theRule)
Add an Able rule (any type) to the end of the rule block.
Parameters:
theRule - The rule to add.


insertRuleAt

protected void insertRuleAt(int theIndex,
                            AbleRule theRule)
Insert an Able rule (any type) at specified position in the rule block.
Parameters:
theRule - The rule to add.
theIndex - the integer position or index where the rule should be inserted (0-based)


removeRule

protected void removeRule(AbleRule theRule)
Remove an Able rule (any type) from the rule block.
Parameters:
theRule - The rule to remove.


replaceRule

protected void replaceRule(AbleRule theOldRule,
                           AbleRule theNewRule)
Replace an Able rule (any type) in the rule block at its current position in the ruleblock. Note the oldRule and newRule could be of different types.
Parameters:
theRule - The rule to be replaced.


getRules

public java.util.Vector getRules()
Retrieve the list of all rules.
Returns:
A cloned list of all rules (both assertions and conditional rules) defined in this rule block. The rules are in the order in which they were added.

getEnabledRules

public java.util.Vector getEnabledRules()
Retrieve the list of all enabled rules. Template rules are not included in this list.
Returns:
A cloned list of all enabled rules (regardless of type) defined in this rule block. The rules are in the order in which they were added.

getAssertions

public java.util.Vector getAssertions()
Retrieve the list of assertion rules.
Returns:
A cloned list of assertion rules defined in this rule block, in declaration order.

getEnabledAssertions

public java.util.Vector getEnabledAssertions()
Retrieve the list of enabled assertion rules. Template rules are not included in this list.
Returns:
A cloned list of enabled assertion rules defined in this rule block, in declaration order.

getConditionalRules

public java.util.Vector getConditionalRules()
Retrieve the list of conditional rules.
Returns:
A cloned list of conditional rules defined in this rule block, in declaration order.

getEnabledConditionalRules

public java.util.Vector getEnabledConditionalRules()
Retrieve the list of enabled conditional rules. Template rules are not included in this list.
Returns:
A cloned list of enabled conditional rules defined in this rule block, in declaration order.

getIfThenElseRules

public java.util.Vector getIfThenElseRules()
Retrieve the list of if-then-else rules.
Returns:
A cloned list of if-then-else rules defined in this rule block, in declaration order.

getEnabledIfThenElseRules

public java.util.Vector getEnabledIfThenElseRules()
Retrieve the list of enabled if-then-else rules. Template rules are not included in this list.
Returns:
A cloned list of enabled if-then-else rules defined in this rule block, in declaration order.

getPatternMatchRules

public java.util.Vector getPatternMatchRules()
Retrieve the list of pattern match rules.
Returns:
A cloned list of pattern match rules defined in this rule block, in declaration order.

getEnabledPatternMatchRules

public java.util.Vector getEnabledPatternMatchRules()
Retrieve the list of enabled pattern match rules. Template rules are not included in this list.
Returns:
A cloned list of enabled pattern match rules defined in this rule block, in declaration order.

getPredicateRules

public java.util.Vector getPredicateRules()
Retrieve the list of predicate facts and rules.
Returns:
A cloned list of predicate facts and rules defined in this rule block, in declaration order.

getEnabledPredicateRules

public java.util.Vector getEnabledPredicateRules()
Retrieve the list of enabled predicate facts and rules. Template rules are not included in this list.
Returns:
A cloned list of enabled predicate facts and rules defined in this rule block, in declaration order.

getIterationRules

public java.util.Vector getIterationRules()
Retrieve the list of iteration rules.
Returns:
A cloned list of iteration rules defined in this rule block, in declaration order.

getEnabledIterationRules

public java.util.Vector getEnabledIterationRules()
Retrieve the list of enabled iteration rules. Template rules are not included in this list.
Returns:
A cloned list of enabled iteration rules defined in this rule block, in declaration order.

arlString

public java.lang.String arlString()
Return a formal Able Rule Language (ARL) String.
Returns:
A String describing the object in able rule language.

xmlString

public java.lang.String xmlString()
Return a formal XML string.
Returns:
A String describing the object in XML.

reset

public void reset()
Reset the rule block so that rules can be fired again: all rules are set to their original state. Note that the "processed" flag is not reset.

setProcessed

public void setProcessed(boolean theProcessedFlag)
Set the flag that indicates whether this rule block has been processed at least once.
Parameters:
theProcessedFlag - Use true to indicate that the rules in this rule block have been processed at least once; use false otherwise.

isProcessed

public boolean isProcessed()
Determine whether this rule block has been processed at least once.
Returns:
true if the rule block has been processed at least once; false otherwise.

getRuleTemplates

public java.util.Vector getRuleTemplates()
                                  throws AbleDataException
Retrieve all rule template objects defined in this ruleblock
Returns:
A vector of all rule templates

getTemplateString

public java.lang.String getTemplateString(java.util.Vector theTemplateVars)
                                   throws AbleDataException
Retrieve a text format string for use by ruleset templates. The string contains "{n}" strings, where the index 'n' corresponds to the template variables defined in the ruleset template. This string is based on the standard arlString() representation of the ruleblock. After replacement of the template variable values, the resulting string must be a valid ARL format string that can be parsed.
Parameters:
theTemplateVars - An ordered list of template variables referenced by this ruleblock.
Returns:
A Text format string used to create a new ruleblock instance.
See Also:
AbleRuleTemplate

getTemplateVars

public java.util.Vector getTemplateVars(AbleRuleSet theRuleSet)
                                 throws AbleDataException
Return a list of template vars referenced by this ruleblock.

getRulesFiredCount

public int getRulesFiredCount()
Returns the number of rules fired by the associated inference engine during the last infer() call

toString

public java.lang.String toString()
Retrieve a string describing (the contents of) the object.
Overrides:
toString in class java.lang.Object
Returns:
A String containing the current contents of the object.

traceString

public java.lang.String traceString(int theTraceStringFlavor)
Retrieve a string describing (the contents of) the object.
Parameters:
theFlavor - An Able.TraceStringFlavor value.

Returns:
A String containing the current contents of the object.

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