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

com.ibm.able.rules
Class AbleRule

java.lang.Object
  |
  +--com.ibm.able.rules.AbleRule
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbleAssertionRule, AbleConditionalRule, AbleDoUntilRule, AbleDoWhileRule, AbleForLoopRule, AbleIfThenElseRule, AblePatternMatchRule, AblePredicateRule, AbleWhileDoRule

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

This class defines an abstract rule from which derived rules can inherit an ID, label, priority, and other parts. How these parts are used is entirely up to inference engines that work on the rules. For example, some inference engines may make use of the priority field while others may not. To a rule itself, priority is nothing more than a field to be set and returned. The same is true of all base rule members.

See Also:
Serialized Form

Field Summary
protected  java.lang.Boolean myBooleanTruth
          myBooleanTruth contains the current truth value of this rule, but only if the rule has been evaluated.
protected  AbleRuleBreakpoint myBreakpoint
          An optional breakpoint assoicated with this rule.
protected  java.lang.String myComment
          "myComment" provides a place to associate a comment with this rule.
protected  boolean myEnabled
          myEnabled indicates whether the rule is enabled for use or not.
protected  int myFiredCount
          myFiredCount indicates how many times this rule has been 'fired', since it was initialized.
protected  boolean myFiredFlag
          myFiredFlag indicates whether the rule has been 'fired', or evaluated.
protected  int myId
          myId is the unique Id of this particular rule.
protected  java.lang.String myLabel
          myLabel is the unique name of this particular rule.
protected  AbleLocation myLocation
          The location of this rule in the source ARL file
protected  java.lang.Object[] myPreConditions
          myPreConditions (if defined) is a list of objects defined in the rule header.
protected  AbleRd myPriority
          myPriority indicates the priority of this rule relative to other rules.
protected  java.lang.String myPrompt
          "myPrompt" provides a place to associate a user prompt with this rule.
protected  java.util.BitSet myRdRefs
          myRdRefs is a list of variables referenced by all the clauses in this rule.
protected  AbleRuleSet myRuleSet
          myRuleSet is a reference to the owning ruleset.
protected  boolean myTemplateFlag
          A flag that indicates whether this rule is a template rule.
protected  java.lang.String myTemplateName
          The name of the template rule from which this rule was generated (if any)
protected  java.lang.Object[] myTemplateValues
          The list of String replacement values used to generate this rule from the template (if any)
protected  java.util.BitSet myWrRefs
          myWrRefs is a list of variables set by the consequent clauses in this rule.
static AbleRd PriorityDefault
          A default priority for rules.
static int RuleIdInitial
          The ID of the first created rule.
 
Constructor Summary
AbleRule(int theId, java.lang.String theLabel, AbleRd thePriority, AbleRuleSet theRuleSet)
          Create a new rule with the specified bits.
 
Method Summary
 java.util.BitSet addHeaderRdReferences()
          Add rule header variable references including priority and rule preConditions.
protected  void addRdReference(int theId)
          Update the list of variables whose values are "read" by clauses in this rule.
protected  void addRdReferences(java.util.BitSet theIds)
          Update the list of variables whose values are "read" by clauses in this rule.
protected  void addWrReference(int theId)
          Update the list of variables whose values are "set" by clauses in this rule.
protected  void addWrReferences(java.util.BitSet theIds)
          Update the list of variables whose values are "set" by clauses in this rule.
protected  java.lang.String arlPreConditionsString()
          Return a formal Able Rule Language (ARL) String for the rule preConditions.
abstract  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.
 void clearBreakpoint()
          Remove the breakpoint from this rule
static java.lang.String Copyright()
          Determine the copyright of this class.
 java.lang.String getArlComment()
          Retrieve the comment associated with this rule as an arl string with javadoc delimiters around it.
 java.lang.Boolean getBooleanTruth()
          Retrieve the rule's overall truth value.
 AbleRuleBreakpoint getBreakpoint()
          Returns the breakpong associated with this rule (or null if none is defined).
 java.lang.String getComment()
          Retrieve the comment associated with this rule.
 int getId()
          Retrieve the rule's unique Id.
 java.lang.String getIdLabelString()
          Retrieve the rule's unique Id and label in a single string.
 java.lang.String getLabel()
          Retrieve the rule's unique label.
 AbleLocation getLocation()
          Returns the location of the rule in the source ARL file
 double getPriority()
          Retrieve the rule's priority.
 java.lang.String getPrompt()
          Retrieve the user prompt associated with this rule.
 java.lang.String getPromptString(AbleRuleSet theRuleSet)
          Retrieve the user prompt string associated with this rule.
 java.util.BitSet getRdReferences()
          Retrieve the list of variable Ids that are referenced by this rule's clauses.
 java.lang.String getTemplateHeaderString(java.util.Vector theTemplateVars)
          Retrieve a text format string for the rule header info for use by rule templates.
 java.lang.String getTemplateName()
          Retrieve the name of the template rule from which this rule was generated (if any)
abstract  java.lang.String getTemplateString(java.util.Vector theTemplateVars)
          Retrieve a text format string for use by templates.
 java.lang.Object[] getTemplateValues()
          Retrieve the String replacement values used to generate this rule from a template
 java.util.Vector getTemplateVars(AbleRuleSet theRuleSet)
          Return a list of template vars referenced by this rule.
 java.util.BitSet getWrReferences()
          Retrieve the list of variable Ids that are set by this rule's consequent clause.
 boolean isEnabled()
          Retrieve the rule's enabled state
 boolean isFired()
          Determine whether the rule has fired.
 boolean isGeneratedFromTemplate()
          Returns true if this rule was generated from a template rule
 boolean isTemplate()
          Returns true if this rule is a template rule, false otherwise.
protected  void logTrace(java.lang.String theLogEntry)
           
 void reset()
          Reset the rule to its unfired state.
 void setBooleanTruth(java.lang.Boolean theTruthValue)
          Set the rule's overall truth value.
 void setBreakpoint(AbleRuleBreakpoint theBreakpoint)
          Set the breakpoint associated with this rule
 void setComment(java.lang.String theComment)
          Set (or change) the comment associated with this rule.
 void setEnabled(boolean theState)
          Set the rule's enabled state Note: this may be ignored by the inference engine
 void setFired(boolean theFiredFlag)
          Set the flag that indicates whether the rule has fired.
 void setId(int theId)
          Set the rule's unique Id.
 void setLocation(AbleLocation theLocation)
          Set the location of the rule in the source ARL file
 void setPreConditions(java.lang.Object[] thePreConditions)
          Set the preConditions on this rule
 void setPriority(AbleRd thePriority)
          Set the rule's priority.
 void setPrompt(java.lang.String thePrompt)
          Set (or change) the user prompt associated with this rule.
 void setTemplate(boolean theTemplateFlag)
          Set the state of the template flag for this rule.
 void setTemplateName(java.lang.String theTemplateName)
          Set the name of the template rule from which this rule was generated
 void setTemplateValues(java.lang.Object[] theTemplateValues)
          Set the String replacement values used to generate this rule from a template
 java.lang.String toString()
          Retrieve a string describing (the contents of) the object.
abstract  java.lang.String traceString(int theTraceStringFlavor)
          Retrieve a string describing (the contents of) the object.
protected  java.lang.String xmlPreConditionsString()
          Return a formal XML string for the rule preConditions.
 java.lang.String xmlPriorityString()
          Return a formal XML string for the rule priority.
abstract  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

PriorityDefault

public static final AbleRd PriorityDefault
A default priority for rules. This priority essentially means "no priority". It is up to an inference engine to make use of rule priorities. The rules themselves do not use priority in any way.

RuleIdInitial

public static final int RuleIdInitial
The ID of the first created rule.

myId

protected int myId
myId is the unique Id of this particular rule.

Note that, in some situations, rules may not need any Id at all so it may not matter whether the Id is unique or even exists. However, in other situations, such as when rules are manipulated by an inference engine, the Id must exist and be guaranteed to be unique. Currently, it is up to the creator of any rule to set the Id appropriately.


myLabel

protected java.lang.String myLabel
myLabel is the unique name of this particular rule.

Note that in some situations, rules may not need any label at all so it may not matter whether the label is unique or even exists. However, in other situations, such as when rules are manipulated by an inference engine, the label must be guaranteed to be unique. Therefore, it is up to the creator of any rule to set the label appropriately.

It is strongly suggested that a label be provided for each and every rule, as the label will appear in various Able windows.


myPriority

protected AbleRd myPriority
myPriority indicates the priority of this rule relative to other rules. It can be a numeric literal, a numeric variable, or an expression that evaluates to a numeric value. Unless explicitly set to something else, the priority is initialized to PriorityDefualt.

myRuleSet

protected AbleRuleSet myRuleSet
myRuleSet is a reference to the owning ruleset.

myRdRefs

protected java.util.BitSet myRdRefs
myRdRefs is a list of variables referenced by all the clauses in this rule. This field depends upon each variable having a unique integer Id.

myWrRefs

protected java.util.BitSet myWrRefs
myWrRefs is a list of variables set by the consequent clauses in this rule. This field depends upon each variable having a unique integer Id.

myFiredFlag

protected boolean myFiredFlag
myFiredFlag indicates whether the rule has been 'fired', or evaluated. The field is initialized to false and set to true whenever the rule is evaluated. The reset() method may be used to change this flag back to false, which has the effect of allowing the rule to fire again.

myFiredCount

protected int myFiredCount
myFiredCount indicates how many times this rule has been 'fired', since it was initialized. Note: reset() does not clear this counter.

myBooleanTruth

protected java.lang.Boolean myBooleanTruth
myBooleanTruth contains the current truth value of this rule, but only if the rule has been evaluated. The current value is always either true, false, or null. null means that the truth value is unknown or cannot be determined. This field is initialized to null.

myEnabled

protected boolean myEnabled
myEnabled indicates whether the rule is enabled for use or not. The field is initialized to true and can be set to false using the API or by a ruleset.

myPreConditions

protected java.lang.Object[] myPreConditions
myPreConditions (if defined) is a list of objects defined in the rule header. The most common usage is to hold a list of TimePeriods which are used to compute whether the rule should be enabled (active) or not.

myComment

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

myPrompt

protected java.lang.String myPrompt
"myPrompt" provides a place to associate a user prompt with this rule. The value is initialized to null.
See Also:
setPrompt(String), getPrompt()

myTemplateFlag

protected boolean myTemplateFlag
A flag that indicates whether this rule is a template rule. Template rules are used to customize ruleset but are not part of the executable ruleset.

myTemplateName

protected java.lang.String myTemplateName
The name of the template rule from which this rule was generated (if any)

myTemplateValues

protected java.lang.Object[] myTemplateValues
The list of String replacement values used to generate this rule from the template (if any)

myLocation

protected AbleLocation myLocation
The location of this rule in the source ARL file

myBreakpoint

protected AbleRuleBreakpoint myBreakpoint
An optional breakpoint assoicated with this rule.
Constructor Detail

AbleRule

public AbleRule(int theId,
                java.lang.String theLabel,
                AbleRd thePriority,
                AbleRuleSet theRuleSet)
Create a new rule with the specified bits.
Parameters:
theId - The unique Id of this rule.

theLabel - The unique label, or name, of this rule.

thePriority - The priority of this rule.

theRuleSet - A ruleset object to which this rule belongs.

Method Detail

setId

public final void setId(int theId)
Set the rule's unique Id.
Returns:
The unique Id of the rule.

getId

public final int getId()
Retrieve the rule's unique Id.
Returns:
The unique Id of the rule.

getLabel

public final java.lang.String getLabel()
Retrieve the rule's unique label.
Returns:
The unique label of the rule.

getIdLabelString

public java.lang.String getIdLabelString()
Retrieve the rule's unique Id and label in a single string.
Returns:
The unique Id and label of the rule in the form: "n(label)"

setComment

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

See Also:
myComment

getComment

public java.lang.String getComment()
Retrieve the comment associated with this rule.
Returns:
A String containing the current comment associated with this rule 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 rule as an arl string with javadoc delimiters around it.
Returns:
A String containing the current comment associated with this rule or the empty string if no comment has been set. The value is never expected to be null.
See Also:
myComment

addRdReference

protected void addRdReference(int theId)
Update the list of variables whose values are "read" by clauses in this rule.
Parameters:
theId - The unique Id of a variable referenced in a clause of this rule.


addRdReferences

protected void addRdReferences(java.util.BitSet theIds)
Update the list of variables whose values are "read" by clauses in this rule.
Parameters:
theIds - The unique Ids of variables referenced in a clause of this rule.


getRdReferences

public java.util.BitSet getRdReferences()
Retrieve the list of variable Ids that are referenced by this rule's clauses.
Returns:
A clone of the list.

addWrReference

protected void addWrReference(int theId)
Update the list of variables whose values are "set" by clauses in this rule.
Parameters:
theId - The unique Id of a variable whose value is set by the consequent clause of this rule.


addWrReferences

protected void addWrReferences(java.util.BitSet theIds)
Update the list of variables whose values are "set" by clauses in this rule.
Parameters:
theIds - The unique Ids of variables whose value is set by the consequent clause of this rule.


getWrReferences

public java.util.BitSet getWrReferences()
Retrieve the list of variable Ids that are set by this rule's consequent clause.
Returns:
A clone of the list.

addHeaderRdReferences

public java.util.BitSet addHeaderRdReferences()
Add rule header variable references including priority and rule preConditions.
Returns:
A bitset of variable ids referenced in the rule header.

setFired

public final void setFired(boolean theFiredFlag)
Set the flag that indicates whether the rule has fired.
Parameters:
theFiredFlag - true if the rule has fired; false otherwise.

isFired

public final boolean isFired()
Determine whether the rule has fired.
Returns:
true if the rule has fired; false otherwise.

reset

public void reset()
Reset the rule to its unfired state.

setBooleanTruth

public final void setBooleanTruth(java.lang.Boolean theTruthValue)
Set the rule's overall truth value.

This method is used by the forward chaining inference engine.

Parameters:
theTruthValue - true if all of the rule's antecedent clauses evaluate to true; false if any of the rule's antecedent clauses evaluate to false; null if the truth value is unknown or cannot be determined.

getBooleanTruth

public final java.lang.Boolean getBooleanTruth()
Retrieve the rule's overall truth value.

This method is used by the forward chaining inference engine.

Returns:
true if all of the rule's antecedent clauses evaluate to true; false if any of the rule's antecedent clauses evaluate to false; null if the truth value is unknown or cannot be determined.

setPriority

public final void setPriority(AbleRd thePriority)
Set the rule's priority.
Parameters:
thePriority - The priority of this rule.

getPriority

public final double getPriority()
                         throws AbleDataException
Retrieve the rule's priority.
Returns:
The priority of the rule.

setEnabled

public void setEnabled(boolean theState)
Set the rule's enabled state Note: this may be ignored by the inference engine
Parameters:
theState - The boolean enabled state of the rule

isEnabled

public boolean isEnabled()
Retrieve the rule's enabled state
Returns:
the boolean enabled state

setPreConditions

public void setPreConditions(java.lang.Object[] thePreConditions)
                      throws AbleDataException
Set the preConditions on this rule

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.

setTemplate

public void setTemplate(boolean theTemplateFlag)
Set the state of the template flag for this rule. If true, this rule is a template which is meta-data and is not an executable rule.

isTemplate

public boolean isTemplate()
Returns true if this rule is a template rule, false otherwise.

arlString

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

arlPreConditionsString

protected java.lang.String arlPreConditionsString()
Return a formal Able Rule Language (ARL) String for the rule preConditions.
Returns:
A String describing the rule preConditions in able rule language.

xmlString

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

xmlPriorityString

public java.lang.String xmlPriorityString()
Return a formal XML string for the rule priority.
Returns:
A String describing the rule priority in XML.

xmlPreConditionsString

protected java.lang.String xmlPreConditionsString()
Return a formal XML string for the rule preConditions.
Returns:
A String describing the rule preConditions in XML.

traceString

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

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

logTrace

protected void logTrace(java.lang.String theLogEntry)

getTemplateString

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

getTemplateHeaderString

public java.lang.String getTemplateHeaderString(java.util.Vector theTemplateVars)
                                         throws AbleDataException
Retrieve a text format string for the rule header info for use by rule templates. The string contains "{n}" strings, where the index 'n' corresponds to the template variables defined in the rule template. This string is based on the standard arlString() representation of the rule. 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 rule.
Returns:
A Text format string used to create a new rule instance.
See Also:
AbleRuleTemplate

getTemplateVars

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

isGeneratedFromTemplate

public boolean isGeneratedFromTemplate()
Returns true if this rule was generated from a template rule

setTemplateName

public void setTemplateName(java.lang.String theTemplateName)
Set the name of the template rule from which this rule was generated

getTemplateName

public java.lang.String getTemplateName()
Retrieve the name of the template rule from which this rule was generated (if any)
Returns:
The name of the template rule or null (if not generated)

setTemplateValues

public void setTemplateValues(java.lang.Object[] theTemplateValues)
Set the String replacement values used to generate this rule from a template

getTemplateValues

public java.lang.Object[] getTemplateValues()
Retrieve the String replacement values used to generate this rule from a template

setPrompt

public void setPrompt(java.lang.String thePrompt)
Set (or change) the user prompt associated with this rule. This is used by UIs associated with the ruleset.
Parameters:
thePrompt - A String containing the user prompt for this rule. This comment replaces the current prompt.

See Also:
myPrompt

getPrompt

public java.lang.String getPrompt()
Retrieve the user prompt associated with this rule.
Returns:
A String containing the current prompt associated with this rule or null if no prompt has been set.
See Also:
myPrompt

getPromptString

public java.lang.String getPromptString(AbleRuleSet theRuleSet)
Retrieve the user prompt string associated with this rule. Note: the contents of this string will depend on whether a resource bundle is associated with the ruleset.

If there is no resource bundle then the prompt string is returned If there is a resource bundle but the myPrompt value is null then a message with the variable name as the key is returned. If there is a resource bundle with a non-null myPrompt value then a message with the myPrompt value as key is returned.

Returns:
A String containing the current user prompt associated with this rule.
See Also:
myPrompt

setLocation

public void setLocation(AbleLocation theLocation)
Set the location of the rule in the source ARL file

getLocation

public AbleLocation getLocation()
Returns the location of the rule in the source ARL file

setBreakpoint

public void setBreakpoint(AbleRuleBreakpoint theBreakpoint)
Set the breakpoint associated with this rule

getBreakpoint

public AbleRuleBreakpoint getBreakpoint()
Returns the breakpong associated with this rule (or null if none is defined).

clearBreakpoint

public void clearBreakpoint()
Remove the breakpoint from this rule

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.

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