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

com.ibm.able.data
Class AbleVariable

java.lang.Object
  |
  +--com.ibm.able.data.AbleLhs
        |
        +--com.ibm.able.data.AbleVariable
All Implemented Interfaces:
AbleRd, AbleWr, java.io.Serializable
Direct Known Subclasses:
AbleContinuousVariable, AbleGenericVariable

public abstract class AbleVariable
extends AbleLhs
implements java.io.Serializable

This class defines the base ABLE data variable object. AbleVariables are used to hold mutable values corresponding to the Java primitive types and to certain other Object types (Object, String, Calendar, etc.). AbleVariables can appear on the left-hand side of assignment statements (as contrasted with AbleLiterals which are treated as constants).

AbleVariables support the "static" modifier, which means that the variable will not be reset to its initial value before each inferencing cycle (when used as part of an AbleRuleSet).

AbleVariables support the "template" modifier, which means that the variable can be used in rule templates as placeholders for customized values.

Variables can be global or local. Global variables are defined in the variables { } section of an AbleRuleSet and can be accessed by all rules in the ruleset. Local variables are limited to a visibility by a single rule.

Initial values are set on the constructor or using the setInitialValue() method. A reset() will set the variable value back to the initial value.

See Also:
Serialized Form

Field Summary
protected  boolean myBoundFlag
          A flag that indicates if this variable's value has been set by an initializer or by an assignment.
protected  java.beans.PropertyChangeSupport myChgSupport
          A set of listeners interested in property changes performed by this variable.
protected  java.lang.String myComment
          "myComment" provides a place to associate a comment with this variable.
protected  java.lang.Object myContext
          The context in which this variable is used.
protected  int myDataType
          An AbleData.<DataType> constant that specifies this particular variable's data type.
protected  boolean myGlobalFlag
          A flag that indicates whether this variable is "global" (true) or "local" (false).
protected  int myId
          The unique Id of this particular variable.
protected  java.lang.String myName
          The unique name of this particular variable.
protected  java.lang.String myPrompt
          "myPrompt" provides a place to associate a user prompt with this variable.
protected  AbleReferences myReferences
          A set of references to this variable.
protected  boolean myStaticFlag
          A flag that indicates whether this variable is "static".
protected  boolean myTemplateFlag
          A flag that indicates whether this variable is a template variable.
protected  AbleRd myValueInitial
          The initial value (literal or expression) of the variable.
 
Constructor Summary
protected AbleVariable(int theDataType, java.lang.String theName)
          Create a new variable of the specified type and with the specified name.
protected AbleVariable(int theDataType, java.lang.String theName, boolean theStaticFlag, boolean theGlobalFlag)
          Create a new variable of the specified type and with the specified name.
 
Method Summary
 java.lang.String arlCRdString()
          Return a formal ARL "clause read" string that describes this data object.
abstract  java.lang.String arlDclString()
          Return a formal ARL "declaration" string that describes this data object.
 java.lang.String arlInitializerString()
           
 java.lang.String getArlComment()
          Retrieve the comment associated with this variable formatted as an arl string with javadoc delmiters around it.
 java.lang.Object getChgSupport()
          Retrieve a reference to the property change support object that this variable uses to notify listeners of changes to this variable's current value.
 java.lang.String getComment()
          Retrieve the comment associated with this variable.
 java.lang.Object getContext()
          Retrieve a reference to the context in which this variable resides.
 int getDataType()
          Retrieve the data type of this data object.
 java.lang.String getDataTypeAsString()
          Retrieve the data type of this variable as a human-readable debug string.
abstract  java.lang.String getDataTypeName()
          Retrieve the data type name.
 int getId()
          Retrieve the unique Id of this variable.
abstract  java.lang.Class getLiteralClass()
          Retrieve the class of this variable's related AbleLiteral data type.
 java.lang.String getName()
          Retrieve the unique name of this variable.
 java.lang.String getPrompt()
          Retrieve the user prompt associated with this variable.
 java.lang.String getPromptString()
          Retrieve the user prompt string associated with this variable.
 AbleReferences getReferences()
          Retrieve the set of objects that refer to this variable.
 int getReferent()
          Retrieve the Id of the variable to which this data object refers, if any.
 java.util.BitSet getReferents()
          Retrieve the Ids of the variables to which this data object refers, if any.
 java.lang.String getTemplateString(java.util.Vector theTemplateVars)
          Return a formatted ARL text string for use by templates
abstract  java.lang.String getValueString()
          Retrieve the variable's current value as a string.
abstract  void init()
          Init the variable to its default or initial state.
 boolean isBound()
          Retrieves the boolean flag that indicates whether this variable's value has been set by an initializer or assignment
 boolean isConstant()
          Returns true if this AbleRd object is a constant value false, if it does not.
 boolean isGlobal()
          Determine whether this variable is global.
 boolean isLocal()
          Determine whether this variable is local.
 boolean isStatic()
          Determine whether this variable is static; that is, whether it will ignore reset requests.
 boolean isTemplate()
          Returns true if this variable is a template variable, false otherwise.
 boolean notStatic()
          Determine whether this variable is not static; that is, whether it will honor reset requests.
abstract  void reset()
          Reset the variable to its initial state subject to static flag (if static is true then variable is not reset).
 void setChgSupport(java.beans.PropertyChangeSupport theChgSupport)
          Set a reference to the property change support object that this variable uses to notify listeners of changes to this variable's current value.
 void setComment(java.lang.String theComment)
          Set (or change) the comment associated with this variable.
 void setContext(java.lang.Object theContext)
          Set a reference to the context in which this variable resides.
 void setId(int theId)
          Set the unique Id of this variable.
 void setInitialValue(AbleRd theInitialValue)
          Set the initial value (literal or expression) for this variable
 void setPrompt(java.lang.String thePrompt)
          Set (or change) the user prompt associated with this variable.
 void setReferences(AbleReferences theReferences)
          Set the set of objects that refer to this variable.
 void setStatic(boolean theStaticFlag)
          Set this variable as static or not static.
 void setTemplate(boolean theTemplateFlag)
          Set the state of the template flag for this variable.
abstract  void setValueString(java.lang.String theNewValue)
          Set the variable's current value from a string.
 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.
 java.lang.String xmlCRdString()
          Return a formal XML "clause read" string that describes this data object.
 java.lang.String xmlCWrString()
          Return a formal XML "clause write" string that describes this data object.
abstract  java.lang.String xmlDclString()
          Return a formal XML "declaration" string that describes this data object.
 java.lang.String xmlInitializerString()
           
 
Methods inherited from class com.ibm.able.data.AbleLhs
asgnEq, asgnIs, asgnIs, bitwiseAND, bitwiseNOT, bitwiseOR, bitwiseShiftLeft, bitwiseShiftRight, bitwiseShiftRightZeroFill, bitwiseXOR, cmpEq, cmpGt, cmpGtEq, cmpIs, cmpLt, cmpLtEq, cmpNeq, compDivide, compMinus, compModulo, compMultiply, compPlus, compUnaryMinus, Copyright, getBooleanValue, getDataTypeClass, getDataTypeClassName, getFuzzyValue, getGenericValue, getNumericValue, getStringValue, getValue, logicalAND, logicalNOT, logicalOR, setBooleanValue, setFuzzyValue, setGenericValue, setNumericValue, setStringValue, setValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

myDataType

protected int myDataType
An AbleData.<DataType> constant that specifies this particular variable's data type.

This field is initialized to AbleData.DataTypeUnknown.


myId

protected int myId
The unique Id of this particular variable.

Note that, in some situations, variables 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 variables are used in rules manipulated by an inference engine, the Id must be guaranteed to be unique. Currently, it is up to the creator of any variable to set the Id appropriately, but this may change in the future.

This field is initialized to AbleData.VarIdNull.


myName

protected java.lang.String myName
The unique name of this particular variable.

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

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

This field is initialized to the empty string ("").


myContext

protected java.lang.Object myContext
The context in which this variable is used.

In some cases, a context is not needed and may be null. In other cases, such as when a variable is used in rules manipulated by an inference engine, the context must be provided. Currently, it is up to the creator of any variable to set the context appropriately.

This field is initialized to null.


myReferences

protected AbleReferences myReferences
A set of references to this variable.

This object allows a variable to keep track of other objects that reference it. Whenever a variable updates its "raw" value, the variable will call this object's updateReferences() method so that those other objects may perform special processing.

Note that in some situations a variable may not give a hoot about what other objects reference it. In this case, this set of references may be null or the empty set. It is up to the creator of any variable to set the references appropriately.

This field is initialized to null.


myChgSupport

protected java.beans.PropertyChangeSupport myChgSupport
A set of listeners interested in property changes performed by this variable.

This object allows a variable to keep track of other objects that are interested in the variable's property changes. Whenever a variable updates its "raw" value, the variable will call this object's firePropertyChange() method so that those other objects may perform special processing.

Note that in some situations nothing may care about property changes. In this case, this set of listeners may be null. It is up to the creator of any variable to set the change support appropriately.

This field is initialized to null.


myStaticFlag

protected boolean myStaticFlag
A flag that indicates whether this variable is "static".

Static variables ignore all calls to reset; that is, their current value is always the value that was last explicitly set.

This field is initialized to false.


myGlobalFlag

protected boolean myGlobalFlag
A flag that indicates whether this variable is "global" (true) or "local" (false).

This field is initialized to true and may be reset when a local variable is constructed.


myValueInitial

protected AbleRd myValueInitial
The initial value (literal or expression) of the variable.

myComment

protected java.lang.String myComment
"myComment" provides a place to associate a comment with this variable. 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 variable. The value is initialized to null.
See Also:
setPrompt(String), getPrompt()

myTemplateFlag

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

myBoundFlag

protected boolean myBoundFlag
A flag that indicates if this variable's value has been set by an initializer or by an assignment.
Constructor Detail

AbleVariable

protected AbleVariable(int theDataType,
                       java.lang.String theName)
Create a new variable of the specified type and with the specified name.
Parameters:
theDataType - An AbleData.<DataType> constant.

theName - The unique name of the variable.


AbleVariable

protected AbleVariable(int theDataType,
                       java.lang.String theName,
                       boolean theStaticFlag,
                       boolean theGlobalFlag)
Create a new variable of the specified type and with the specified name. Also indicate whether the variable is static.
Parameters:
theDataType - An AbleData.<DataType> constant.

theName - The unique name of the variable.

theStaticFlag - Use true if this variable is to be marked as static, which means that it will ignore future reset requests; use false if the variable can be reset to its initial value when requested.

theGlobalFlag - Use true if this variable is to be marked as global; use false if the variable is considered local.

Method Detail

getReferent

public int getReferent()
Retrieve the Id of the variable to which this data object refers, if any.
Overrides:
getReferent in class AbleLhs
Returns:
The Id of the variable to which this data object refers, or AbleData.VarIdNull if the data object is a literal and therefore refers to no variable.

getReferents

public java.util.BitSet getReferents()
Retrieve the Ids of the variables to which this data object refers, if any. Must be overriden by subclasses which can refer to variables.
Returns:
The Ids of the variables to which this data object refers, or AbleData.VarIdNull if the data object is a literal and therefore refers to no variable.

getDataType

public int getDataType()
Retrieve the data type of this data object.
Overrides:
getDataType in class AbleLhs
Returns:
An AbleData.<DataType> constant.

arlCRdString

public java.lang.String arlCRdString()
Return a formal ARL "clause read" string that describes this data object.
Overrides:
arlCRdString in class AbleLhs
Returns:
A String describing the data object in formal rule language.

xmlCRdString

public java.lang.String xmlCRdString()
Return a formal XML "clause read" string that describes this data object.
Overrides:
xmlCRdString in class AbleLhs
Returns:
A String describing the data object in XML.

traceString

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

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

arlDclString

public abstract java.lang.String arlDclString()
Return a formal ARL "declaration" string that describes this data object.
Overrides:
arlDclString in class AbleLhs
Returns:
A String describing the data object in formal rule language.

getTemplateString

public java.lang.String getTemplateString(java.util.Vector theTemplateVars)
Return a formatted ARL text string for use by templates

xmlDclString

public abstract java.lang.String xmlDclString()
Return a formal XML "declaration" string that describes this data object.
Overrides:
xmlDclString in class AbleLhs
Returns:
A String describing the data object in XML.

xmlCWrString

public java.lang.String xmlCWrString()
Return a formal XML "clause write" string that describes this data object.
Overrides:
xmlCWrString in class AbleLhs
Returns:
A String describing the data object in XML.

xmlInitializerString

public java.lang.String xmlInitializerString()

arlInitializerString

public java.lang.String arlInitializerString()

setValueString

public abstract void setValueString(java.lang.String theNewValue)
                             throws AbleDataException
Set the variable's current value from a string. Note: This method is provided for the use of a rule language parser.

getValueString

public abstract java.lang.String getValueString()
Retrieve the variable's current value as a string. Note: This method is provided for the use of a rule language parser.

init

public abstract void init()
                   throws AbleDataException
Init the variable to its default or initial state.

reset

public abstract void reset()
                    throws AbleDataException
Reset the variable to its initial state subject to static flag (if static is true then variable is not reset).

getLiteralClass

public abstract java.lang.Class getLiteralClass()
Retrieve the class of this variable's related AbleLiteral data type.
Returns:
The class of the literal data type.

getDataTypeAsString

public java.lang.String getDataTypeAsString()
Retrieve the data type of this variable as a human-readable debug string.
Returns:
A String describing the data type of this variable.

getDataTypeName

public abstract java.lang.String getDataTypeName()
Retrieve the data type name. This is the name used in the ABLE Rule Set, for example, Integer, Customer, etc. not the underlying class name which is usually different TypedVariables return the name of the imported type. Built-in variables return the built-in type (i.e. Integer).

setId

public void setId(int theId)
Set the unique Id of this variable.
Parameters:
theId - An integer, which is the unique Id of this variable.


getId

public int getId()
Retrieve the unique Id of this variable.
Returns:
An integer, which is the unique Id of this variable.

getName

public java.lang.String getName()
Retrieve the unique name of this variable.
Returns:
A string, which is the unique name of this variable.

setContext

public void setContext(java.lang.Object theContext)
Set a reference to the context in which this variable resides. Note that this may be null if the variable is not part of any context, such as an inferencing system.
Parameters:
theContext - A reference to an Object, or null.


getContext

public java.lang.Object getContext()
Retrieve a reference to the context in which this variable resides. Note that this may be null if the variable is not part of any context, such as an inferencing system.
Returns:
A reference to an Object, or null.

setComment

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

See Also:
myComment

getComment

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

setPrompt

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

See Also:
myPrompt

getPrompt

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

getPromptString

public java.lang.String getPromptString()
Retrieve the user prompt string associated with this variable. 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 variable.
See Also:
myPrompt

setChgSupport

public void setChgSupport(java.beans.PropertyChangeSupport theChgSupport)
Set a reference to the property change support object that this variable uses to notify listeners of changes to this variable's current value. Note that this may be null if no property change support object is needed.
Parameters:
theChgSupport - A reference to a PropertyChangeSupport object, or null.


getChgSupport

public java.lang.Object getChgSupport()
Retrieve a reference to the property change support object that this variable uses to notify listeners of changes to this variable's current value. Note that this may be null if no property change support object has been set.
Returns:
A reference to a PropertyChangeSupport object, or null.

setReferences

public void setReferences(AbleReferences theReferences)
Set the set of objects that refer to this variable. Note that this may be null if the variable is used in a context where it doesn't care what other objects might refer to it.
Parameters:
theReferences - A set of Objects that refer to this variable. The set may be the empty set, or null.


getReferences

public AbleReferences getReferences()
Retrieve the set of objects that refer to this variable. Note that this may be null or the empty set.
Returns:
A reference to the set of objects that refer to this variable, or null if no set of objects has been set.

setStatic

public void setStatic(boolean theStaticFlag)
Set this variable as static or not static.
Parameters:
theStaticFlag - Use true if this variable is to be marked as static, which means that it will ignore future reset requests; use false if the variable can be reset to its initial value when requested.


isStatic

public boolean isStatic()
Determine whether this variable is static; that is, whether it will ignore reset requests.
Returns:
true if this variable is static and ignores reset requests, false otherwise.

notStatic

public boolean notStatic()
Determine whether this variable is not static; that is, whether it will honor reset requests.
Returns:
true if this variable is not static and honors reset requests, false otherwise.

isGlobal

public boolean isGlobal()
Determine whether this variable is global.
Returns:
true if this variable is global; false otherwise.

isLocal

public boolean isLocal()
Determine whether this variable is local.
Returns:
true if this variable is local; false otherwise.

isBound

public boolean isBound()
Retrieves the boolean flag that indicates whether this variable's value has been set by an initializer or assignment
Returns:
true if the variable has been bound

isConstant

public boolean isConstant()
Description copied from interface: AbleRd
Returns true if this AbleRd object is a constant value false, if it does not.
Overrides:
isConstant in class AbleLhs

setInitialValue

public void setInitialValue(AbleRd theInitialValue)
                     throws AbleDataException
Set the initial value (literal or expression) for this variable
Parameters:
theInitialValue - An AbleLiteral or AbleExpression used to set the initial value

setTemplate

public void setTemplate(boolean theTemplateFlag)
Set the state of the template flag for this variable. Template variables are ONLY used to customize templates. They are not used in run-time processing of the ruleset.

isTemplate

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

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.

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

(C) Copyright IBM Corporation 1999, 2003