ptolemy.data.expr

Class Variable

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.kernel.util.AbstractSettableAttribute

ptolemy.data.expr.Variable

All Implemented Interfaces:

java.lang.Cloneable, HasTypeConstraints, Typeable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Settable, ValueListener

Direct Known Subclasses:

NamedObjVariable, Parameter, PTDBSearchAttribute, TemporaryVariable

public class Variable
extends AbstractSettableAttribute
implements Typeable, ValueListener

A Variable is an Attribute that contains a token, and can be set by an expression that can refer to other variables.

A variable can be given a token or an expression as its value. To create a variable with a token, either call the appropriate constructor, or create the variable with the appropriate container and name, and then call setToken(). To set the value from an expression, call setExpression(). The expression is not actually evaluated until you call getToken(), getType(). By default, it is also evaluated when you call validate(), unless you have called setLazy(true), in which case it will only be evaluated if there are other variables that depend on it and those have not had setLazy(true) called.

Consider for example the sequence:

 Variable v3 = new Variable(container,"v3");
 Variable v2 = new Variable(container,"v2");
 Variable v1 = new Variable(container,"v1");
 v3.setExpression("v1 + v2");
 v2.setExpression("1.0");
 v1.setExpression("2.0");
 v3.getToken();
 

Notice that the expression for v3 cannot be evaluated when it is set because v2 and v1 do not yet have values. But there is no problem because the expression is not evaluated until getToken() is called. Equivalently, we could have called, for example,

 v3.validate();
 

This will force v3 to be evaluated, and also v1 and v2 to be evaluated.

There is a potentially confusing subtlety. In the above code, before the last line is executed, the expression for v3 has not been evaluated, so the dependence that v3 has on v1 and v2 has not been recorded. Thus, if we call

 v1.validate();
 

before v3 has ever been evaluated, then it will not trigger an evaluation of v3. Because of this, we recommend that user code call validate() immediately after calling setExpression().

If the expression string is null or empty, or if no value has been specified, then getToken() will return null.

The expression can reference variables that are in scope before the expression is evaluated (i.e., before getToken() or validate() is called). Otherwise, getToken() will throw an exception. All variables contained by the same container, and those contained by the container's container, are in the scope of this variable. Thus, in the above, all three variables are in each other's scope because they belong to the same container. If there are variables in the scope with the same name, then those lower in the hierarchy shadow those that are higher. An instance of ScopeExtendingAttribute can also be used to aggregate a set of variables and add them to the scope.

If a variable is referred to by expressions of other variables, then the name of the variable must be a valid identifier as defined by the Ptolemy II expression language syntax. A valid identifier starts with a letter or underscore, and contains letters, underscores, numerals, dollar signs ($), at signs (@), or pound signs (#).

A variable is a Typeable object. Constraints on its type can be specified relative to other Typeable objects (as inequalities on the types), or relative to specific types. The former are called dynamic type constraints, and the latter are called static type constraints. Static type constraints are specified by the methods:

• setTypeEquals()
• setTypeAtMost()

whereas dynamic type constraints are given by

• setTypeAtLeast()
• setTypeSameAs()

Static type constraints are enforced in this class, meaning that:

• If the variable already has a value (set by setToken() or setExpression()) when you set the static type constraint, then the value must satisfy the type constraint; and
• If after setting a static type constraint you give the token a value, then the value must satisfy the constraints.

A violation will cause an exception (either when setToken() is called or when the expression is evaluated).

The dynamic type constraints are not enforced in this class, but merely reported by the typeConstraints() method. They must be enforced at a higher level (by a type system) since they involve a network of variables and other typeable objects. In fact, if the variable does not yet have a value, then a type system may use these constraints to infer what the type of the variable needs to be, and then call setTypeEquals().

The token returned by getToken() is always an instance of the class given by the getType() method. This is not necessarily the same as the class of the token that was inserted via setToken(). It might be a distinct type if the token given by setToken() can be converted losslessly into one of the type given by setTypeEquals().

A variable by default has no MoML description (MoML is an XML modeling markup language). Thus, a variable contained by a named object is not persistent, in that if the object is exported to a MoML file, the variable will not be represented. If you prefer that the variable be represented, then you should use the derived class Parameter instead.

A variable is also normally not settable by casual users from the user interface. This is because, by default, getVisibility() returns EXPERT. The derived class Parameter is fully visible by default.

In addition, this class provides as a convenience a "string mode." If the variable is in string mode, then when setting the value of this variable, the string that you pass to setExpression(String) is taken to be literally the value of the instance of StringToken that represents the value of this parameter. It is not necessary to enclose it in quotation marks (and indeed, if you do, the quotation marks will become part of the value of the string). In addition, the type of this parameter will be set to string. In addition, getToken() will never return null; if the value of the string has never been set, then an instance of StringToken is returned that has an empty string as its value. A parameter is in string mode if either setStringMode(true) has been called or it contains an attribute named "_stringMode".

In string mode, the value passed to setExpression(String) may contain references to other variables in scope using the syntax $id, ${id} or $(id). The first case only works if the id consists only of alphanumeric characters and/or underscore, and if the character immediately following the id is not one of these. To get a simple dollar sign, use $$. In string mode, to set the value to be the empty string, create a Parameter in the container that has the value "" and then set the string mode parameter to the $nameOfTheParameter. For example, the parameter might be named myEmptyParameter and have a value ""; the value for the string mode parameter would be $myEmptyParameter.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Neil Smyth, Xiaojun Liu, Edward A. Lee, Yuhong Xiong, contributor: Daniel Crawl.

See Also:

Token, PtParser, Parameter, ScopeExtendingAttribute, NamedObj.setPersistent(boolean)

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (neuendor)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Variable.CircularDependencyError Subclass of IllegalActionException for use in reporting circular dependency errors.
protected class	Variable.VariableScope Scope implementation with local caching.

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Nested classes/interfaces inherited from interface ptolemy.kernel.util.Settable

Settable.Visibility

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_currentExpression Stores the expression used to set this variable.
protected boolean	_needsEvaluation Flags that the expression needs to be evaluated when the value of this variable is queried.
protected ParserScope	_parserScope The instance of VariableScope.
protected boolean	_parseTreeValid Indicator that the parse tree is valid.
protected boolean	_suppressVariableSubstitution True to suppress variable substitution in string mode.
protected java.util.List<ValueListener>	_valueListeners Listeners for changes in value.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.kernel.util.Settable

EXPERT, FULL, NONE, NOT_EDITABLE

Constructor Summary

Constructors

Modifier	Constructor and Description
	Variable() Construct a variable in the default workspace with an empty string as its name.
	Variable(NamedObj container, java.lang.String name) Construct a variable with the given name as an attribute of the given container.
	Variable(NamedObj container, java.lang.String name, Token token) Construct a variable with the given container, name, and token.
protected	Variable(NamedObj container, java.lang.String name, Token token, boolean incrementWorkspaceVersion) Construct a variable with the given container, name, and token.
	Variable(Workspace workspace) Construct a variable in the specified workspace with an empty string as its name.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	_description(int detail, int indent, int bracket) Return a description of this variable.
protected void	_evaluate() Evaluate the current expression to a token.
protected java.lang.String	_getCurrentExpression() Get the current expression as a string, to be used to export to MoML.
protected void	_notifyValueListeners() Notify the value listeners of this variable that this variable changed.
protected void	_parseIfNecessary() Parse the expression, if the current parse tree is not valid.
protected java.util.List<IllegalActionException>	_propagate() Force evaluation of this variable, unless it is lazy, and call _propagate() on its value dependents.
protected java.util.List<IllegalActionException>	_propagateToValueListeners() Call propagate() on all value listeners.
protected void	_propagateValue(NamedObj destination) Propagate the value of this object to the specified object.
protected void	_setToken(Token newToken) Set the token value and type of the variable.
protected void	_setTokenAndNotify(Token newToken) Set the token value and type of the variable, and notify the container that the value (and type, if appropriate) has changed.
void	addValueListener(ValueListener listener) Add a listener to be notified when the value of this variable changes.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the variable.
Type	getDeclaredType() If setTypeEquals() has been called, then return the type specified there.
java.lang.String	getExpression() Get the expression currently used by this variable.
java.util.Set	getFreeIdentifiers() Return the list of identifiers referenced by the current expression.
ParserScope	getParserScope() Return the parser scope for this variable.
NamedList	getScope() Return a NamedList of the variables that the value of this variable can depend on.
static NamedList	getScope(NamedObj object) Return a NamedList of the variables that the value of the specified variable can depend on.
Token	getToken() Get the token contained by this variable.
Type	getType() Get the type of this variable.
InequalityTerm	getTypeTerm() Return an InequalityTerm whose value is the type of this variable.
java.lang.String	getValueAsString() Get the value of the attribute, which is the evaluated expression.
Variable	getVariable(java.lang.String name) Look up and return the attribute with the specified name in the scope.
Settable.Visibility	getVisibility() Get the visibility of this variable, as set by setVisibility().
void	invalidate() Mark this variable, and all variables that depend on it, as needing to be evaluated.
boolean	isKnown() Return true if the value of this variable is known, and false otherwise.
boolean	isLazy() Return true if this variable is lazy.
boolean	isStringMode() Return true if this parameter is in string mode.
boolean	isSuppressVariableSubstitution() Return true if this variable is suppressing variable substitution.
boolean	isTypeAcceptable() Check whether the current type of this variable is acceptable.
void	removeValueListener(ValueListener listener) Remove a listener from the list of listeners that is notified when the value of this variable changes.
void	reset() Deprecated. This capability may be removed to simplify this class. It is not currently used in Ptolemy II, as of version 2.0.
void	setContainer(NamedObj container) Specify the container, and add this variable to the list of attributes in the container.
void	setExpression(java.lang.String expr) Set the expression of this variable.
void	setLazy(boolean lazy) Specify whether this variable is to be lazy.
void	setName(java.lang.String name) Override the base class to throw an exception if renaming this variable results in an error evaluating some variable that depends on it.
void	setParseTreeEvaluator(ParseTreeEvaluator parseTreeEvaluator) Set a new parseTreeEvaluator.
void	setStringMode(boolean stringMode) Specify whether this parameter should be in string mode.
void	setSuppressVariableSubstitution(boolean suppress) If the argument is true, then for a string mode parameter, suppress variable substitution.
void	setToken(java.lang.String expression) Set the expression for this variable by calling setExpression(), and then evaluate it by calling validate().
void	setToken(Token token) Put a new token in this variable and notify the container and and value listeners.
void	setTypeAtLeast(InequalityTerm typeTerm) Constrain the type of this variable to be equal to or greater than the type represented by the specified InequalityTerm.
void	setTypeAtLeast(Typeable lesser) Constrain the type of this variable to be equal to or greater than the type of the specified object.
void	setTypeAtMost(Type type) Set a type constraint that the type of this object be less than or equal to the specified class in the type lattice.
void	setTypeEquals(Type type) Set a type constraint that the type of this object equal the specified value.
void	setTypeSameAs(Typeable equal) Constrain the type of this variable to be the same as the type of the specified object.
void	setUnknown(boolean value) Mark the value of this variable to be unknown if the argument is true, or known if the argument is false.
void	setValueListenerAsWeakDependency(ValueListener listener) Set a value listener as a weak dependency.
void	setVisibility(Settable.Visibility visibility) Set the visibility of this variable.
java.lang.String	stringRepresentation() Deprecated.
java.lang.String	toString() Return a string representation of the current evaluated variable value.
java.util.List	typeConstraintList() Deprecated. Use typeConstraints().
java.util.Set<Inequality>	typeConstraints() Return the type constraints of this variable.
java.util.Collection	validate() If this variable is not lazy (the default) then evaluate the expression contained in this variable, and notify any value dependents.
void	valueChanged(Settable settable) React to the change in the specified instance of Settable.

Methods inherited from class ptolemy.kernel.util.AbstractSettableAttribute

getDefaultExpression

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.kernel.util.Settable

getDisplayName

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getFullName, getName, getName

Field Detail

_currentExpression

protected java.lang.String _currentExpression

Stores the expression used to set this variable. It is null if the variable was set from a token.

_needsEvaluation

protected boolean _needsEvaluation

Flags that the expression needs to be evaluated when the value of this variable is queried.

_parseTreeValid

protected boolean _parseTreeValid

Indicator that the parse tree is valid.

_parserScope

protected ParserScope _parserScope

The instance of VariableScope.

_suppressVariableSubstitution

protected boolean _suppressVariableSubstitution

True to suppress variable substitution in string mode.

_valueListeners

protected java.util.List<ValueListener> _valueListeners

Listeners for changes in value.

Constructor Detail

Variable

public Variable()

Construct a variable in the default workspace with an empty string as its name. The variable is added to the list of objects in the workspace. Increment the version number of the workspace.

Variable

public Variable(NamedObj container,
                java.lang.String name)
         throws IllegalActionException,
                NameDuplicationException

Construct a variable with the given name as an attribute of the given container. The container argument must not be null, otherwise a NullPointerException will be thrown. This variable will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:

container - The container.

name - The name of the variable.

Throws:

IllegalActionException - If the container does not accept a variable as its attribute.

NameDuplicationException - If the name coincides with a variable already in the container.

Variable

public Variable(NamedObj container,
                java.lang.String name,
                Token token)
         throws IllegalActionException,
                NameDuplicationException

Construct a variable with the given container, name, and token. The container argument must not be null, or a NullPointerException will be thrown. This variable will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.

Parameters:

container - The container.

name - The name.

token - The token contained by this variable.

Throws:

IllegalActionException - If the container does not accept a variable as its attribute.

NameDuplicationException - If the name coincides with a variable already in the container.

Variable

public Variable(Workspace workspace)

Construct a variable in the specified workspace with an empty string as its name. The name can be later changed with setName(). If the workspace argument is null, then use the default workspace. The variable is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the variable.

Variable

protected Variable(NamedObj container,
                   java.lang.String name,
                   Token token,
                   boolean incrementWorkspaceVersion)
            throws IllegalActionException,
                   NameDuplicationException

Construct a variable with the given container, name, and token. The container argument must not be null, or a NullPointerException will be thrown. This variable will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.

Parameters:

container - The container.

name - The name.

token - The token contained by this variable.

incrementWorkspaceVersion - False to not add this to the workspace or do anything else that might change the workspace version number.

Throws:

IllegalActionException - If the container does not accept a variable as its attribute.

NameDuplicationException - If the name coincides with a variable already in the container.

Method Detail

addValueListener

public void addValueListener(ValueListener listener)

Add a listener to be notified when the value of this variable changes.

Specified by:

addValueListener in interface Settable

Parameters:

listener - The listener to add.

See Also:

removeValueListener(ValueListener)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. This method is called by a contained attribute when its value changes. This overrides the base class so that if the attribute is an instance of TypeAttribute, then it sets the type of the port.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container.

clone

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

Clone the variable. This creates a new variable containing the same token (if the value was set with setToken()) or the same (unevaluated) expression, if the expression was set with setExpression(). The list of variables added to the scope is not cloned; i.e., the clone has an empty scope. The clone has the same static type constraints (those given by setTypeEquals() and setTypeAtMost()), but none of the dynamic type constraints (those relative to other variables).

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace in which to place the cloned variable.

Returns:

The cloned variable.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class.

See Also:

Object.clone()

getDeclaredType

public Type getDeclaredType()

If setTypeEquals() has been called, then return the type specified there. Otherwise, return BaseType.UNKNOWN.

Returns:

The declared type of this variable.

See Also:

setTypeEquals(Type), BaseType

getExpression

public java.lang.String getExpression()

Get the expression currently used by this variable. The expression is either the value set by setExpression(), or a string representation of the value set by setToken(), or an empty string if no value has been set.

Specified by:

getExpression in interface Settable

Returns:

The expression used by this variable.

See Also:

setExpression(String)

getFreeIdentifiers

public java.util.Set getFreeIdentifiers()
                                 throws IllegalActionException

Return the list of identifiers referenced by the current expression.

Returns:

A set of Strings.

Throws:

IllegalActionException - If the expression cannot be parsed.

getParserScope

public ParserScope getParserScope()

Return the parser scope for this variable.

Returns:

The parser scope.

getScope

public NamedList getScope()

Return a NamedList of the variables that the value of this variable can depend on. These include other variables contained by the same container or any container that deeply contains this variable, as well as any variables in a ScopeExtendingAttribute contained by any of these containers. If there are variables with the same name in these various places, then they are shadowed as follows. A variable contained by the container of this variable has priority, followed by variables in a ScopeExtendingAttribute, followed by by a variable contained by the container of the container, etc.

Note that this method is an extremely inefficient to refer to the scope of a variable because it constructs a list containing every variable in the scope. It is best to avoid calling it and instead just use the get() method of the VariableScope inner class.

This method is read-synchronized on the workspace.

Returns:

The variables on which this variable can depend.

getScope

public static NamedList getScope(NamedObj object)

Return a NamedList of the variables that the value of the specified variable can depend on. These include other variables contained by the same container or any container that deeply contains the specified variable, as well as any variables in a ScopeExtendingAttribute contained by any of these containers. If there are variables with the same name in these various places, then they are shadowed as follows. A variable contained by the container of this variable has priority, followed by variables in a ScopeExtendingAttribute, followed by by a variable contained by the container of the container, etc.

Note that this method is an extremely inefficient way to refer to the scope of a variable because it constructs a list containing every variable in the scope. It is best to avoid calling it and instead just use the get() method of the VariableScope inner class.

This method is read-synchronized on the workspace.

Parameters:

object - The NamedObj variable

Returns:

The variables on which this variable can depend.

getToken

public Token getToken()
               throws IllegalActionException

Get the token contained by this variable. The type of the returned token is always that returned by getType(). Calling this method will trigger evaluation of the expression, if the value has been given by setExpression(). Notice the evaluation of the expression can trigger an exception if the expression is not valid, or if the result of the expression violates type constraints specified by setTypeEquals() or setTypeAtMost(), or if the result of the expression is null and there are other variables that depend on this one. The returned value will be null if neither an expression nor a token has been set, or either has been set to null.

Returns:

The token contained by this variable converted to the type of this variable, or null if there is none.

Throws:

IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

See Also:

setToken(String), setToken(ptolemy.data.Token)

getType

public Type getType()

Get the type of this variable. If a token has been set by setToken(), the returned type is the type of that token; If an expression has been set by setExpression(), and the expression can be evaluated, the returned type is the type the evaluation result. If the expression cannot be evaluated at this time, the returned type is the declared type of this Variable, which is either set by setTypeEquals(), or the default BaseType.UNKNOWN; If no token has been set by setToken(), no expression has been set by setExpression(), and setTypeEquals() has not been called, the returned type is BaseType.UNKNOWN.

Specified by:

getType in interface Typeable

Returns:

The type of this variable.

getTypeTerm

public InequalityTerm getTypeTerm()

Return an InequalityTerm whose value is the type of this variable.

Specified by:

getTypeTerm in interface Typeable

Returns:

An InequalityTerm.

getValueAsString

public java.lang.String getValueAsString()

Get the value of the attribute, which is the evaluated expression. If the value is null, this returns the string "null"

Specified by:

getValueAsString in interface Settable

Overrides:

getValueAsString in class AbstractSettableAttribute

Returns:

The same as getExpression().

See Also:

getExpression()

getVariable

public Variable getVariable(java.lang.String name)
                     throws IllegalActionException

Look up and return the attribute with the specified name in the scope. Return null if such an attribute does not exist.

Parameters:

name - The name of the variable to be looked up.

Returns:

The attribute with the specified name in the scope.

Throws:

IllegalActionException - If a value in the scope exists with the given name, but cannot be evaluated.

getVisibility

public Settable.Visibility getVisibility()

Get the visibility of this variable, as set by setVisibility(). The visibility is set by default to EXPERT.

Specified by:

getVisibility in interface Settable

Returns:

The visibility of this variable.

See Also:

setVisibility(Settable.Visibility)

invalidate

public void invalidate()

Mark this variable, and all variables that depend on it, as needing to be evaluated. Remove this variable from being notified by the variables it used to depend on. Then notify other variables that depend on this one that its value has changed. That notification is done by calling their valueChanged() method, which flags them as needing to be evaluated. This might be called when something in the scope of this variable changes.

isKnown

public boolean isKnown()
                throws IllegalActionException

Return true if the value of this variable is known, and false otherwise. In domains with fixed-point semantics, such as SR, a variable that depends on a port value may be unknown at various points during the execution.

Returns:

True if the value is known.

Throws:

IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

See Also:

setUnknown(boolean)

isLazy

public boolean isLazy()

Return true if this variable is lazy. By default, a variable is not lazy.

Returns:

True if this variable is lazy.

See Also:

setLazy(boolean)

isStringMode

public boolean isStringMode()

Return true if this parameter is in string mode.

Returns:

True if this parameter is in string mode.

See Also:

setStringMode(boolean)

isSuppressVariableSubstitution

public boolean isSuppressVariableSubstitution()

Return true if this variable is suppressing variable substitution. That is, it is ignoring dollar signs in the string and does not evaluate substrings such as $name and ${name}. By default, this returns false.

Returns:

True if suppressing variable substitution.

See Also:

isStringMode(), setSuppressVariableSubstitution(boolean)

isTypeAcceptable

public boolean isTypeAcceptable()

Check whether the current type of this variable is acceptable. A type is acceptable if it represents an instantiable object.

Specified by:

isTypeAcceptable in interface Typeable

Returns:

True if the current type is acceptable.

removeValueListener

public void removeValueListener(ValueListener listener)

Remove a listener from the list of listeners that is notified when the value of this variable changes. If no such listener exists, do nothing.

Specified by:

removeValueListener in interface Settable

Parameters:

listener - The listener to remove.

See Also:

addValueListener(ValueListener)

reset

@Deprecated
public void reset()

Deprecated. This capability may be removed to simplify this class. It is not currently used in Ptolemy II, as of version 2.0.

Reset the variable to its initial value. If the variable was originally set from a token, then this token is placed again in the variable, and the type of the variable is set to equal that of the token. If the variable was originally given an expression, then this expression is placed again in the variable (but not evaluated), and the type is reset to BaseType.UNKNOWN. The type will be determined when the expression is evaluated or when type resolution is done. Note that if this variable is cloned, then reset on the clone behaves exactly as reset on the original.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Specify the container, and add this variable to the list of attributes in the container. If this variable already has a container, remove this variable from the attribute list of the current container first. Otherwise, remove it from the directory of the workspace, if it is there. If the specified container is null, remove this variable from the list of attributes of the current container. If the specified container already contains an attribute with the same name, then throw an exception and do not make any changes. Similarly, if the container is not in the same workspace as this variable, throw an exception. If this variable is already contained by the specified container, do nothing.

If this method results in a change of container (which it usually does), then remove this variable from the scope of any scope dependent of this variable.

This method is write-synchronized on the workspace and increments its version number.

Overrides:

setContainer in class Attribute

Parameters:

container - The proposed container of this variable.

Throws:

IllegalActionException - If the container will not accept a variable as its attribute, or this variable and the container are not in the same workspace, or the proposed container would result in recursive containment.

NameDuplicationException - If the container already has an attribute with the name of this variable.

See Also:

Attribute.getContainer()

setExpression

public void setExpression(java.lang.String expr)

Set the expression of this variable. Evaluation is deferred until the value of the variable is accessed by getToken(). The container is not notified of the change until then. If you need to notify the container right away, then call getToken(). If the argument is null, then getToken() will return null. However, if there are other variables that depend on its value, then upon evaluation to null, an exception will be thrown (by getToken()). If the type of this variable has been set with setTypeEquals(), then upon evaluation, the token will be converted into that type, if possible, or an exception will be thrown, if not. If setTypeAtMost() has been called, then upon evaluation, it will be verified that the type constraint is satisfied, and if not, an exception will be thrown.

Specified by:

setExpression in interface Settable

Overrides:

setExpression in class AbstractSettableAttribute

Parameters:

expr - The expression for this variable.

See Also:

getExpression()

setLazy

public void setLazy(boolean lazy)

Specify whether this variable is to be lazy. By default, it is not. A lazy variable is a variable that is not evaluated until its value is needed. Its value is needed when getToken() or getType() is called, but not necessarily when validate() is called. In particular, validate() has the effect only of setting a flag indicating that the variable needs to be evaluated, but the evaluation is not performed. Thus, although validate() returns, there is no assurance that the expression giving the value of the variable can be evaluated without error. The validate() method, however, will validate value dependents. If those are also lazy, then they will not be evaluated either. If they are not lazy however (they are eager), then evaluating them may cause this variable to be evaluated.

A lazy variable may be used whenever its value will be actively accessed via getToken() when it is needed, and its type will be actively accessed via getType(). In particular, the container does not rely on a call to attributeChanged() or attributeTypeChanged() to notify it that the variable value has changed. Those methods will not be called when the value of the variable changes due to some other variable value that it depends on changing because the new value will not be immediately evaluated.

Parameters:

lazy - True to make the variable lazy.

See Also:

validate(), NamedObj.attributeChanged(Attribute), NamedObj.attributeTypeChanged(Attribute)

setName

public void setName(java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException

Override the base class to throw an exception if renaming this variable results in an error evaluating some variable that depends on it. In this case, the name remains unchanged.

Specified by:

setName in interface Nameable

Overrides:

setName in class Attribute

Parameters:

name - The new name.

Throws:

IllegalActionException - If the name contains a period or if this variable is referenced in some other expression.

NameDuplicationException - If there is already an attribute with the same name in the container.

See Also:

NamedObj.getName(), NamedObj.getName(NamedObj)

setParseTreeEvaluator

public void setParseTreeEvaluator(ParseTreeEvaluator parseTreeEvaluator)

Set a new parseTreeEvaluator.

Parameters:

parseTreeEvaluator - The new parseTreeEvaluator used by this variable.

setStringMode

public void setStringMode(boolean stringMode)
                   throws IllegalActionException

Specify whether this parameter should be in string mode. If the argument is true, then specify that the type of this parameter is string. Otherwise, specify that the type is unknown. Note that it probably does not make sense to switch between string mode and not string mode after the variable has a value. Note that this has the side effect of causing any $name or ${name} references in the string value to be replaced with value of a parameter named "name" in scope. To suppress this behavior, invoke setSuppressVariableSubstitution(boolean).

Parameters:

stringMode - True to put the parameter in string mode.

Throws:

IllegalActionException - If the current value of this parameter is incompatible with the resulting type.

See Also:

isStringMode()

setSuppressVariableSubstitution

public void setSuppressVariableSubstitution(boolean suppress)

If the argument is true, then for a string mode parameter, suppress variable substitution. That is, ignore dollar signs in the string and do not evaluate substrings such as $name and ${name}. By default, this is false.

Parameters:

suppress - True to suppress variable substitution.

See Also:

setStringMode(boolean), isSuppressVariableSubstitution()

setToken

public void setToken(java.lang.String expression)
              throws IllegalActionException

Set the expression for this variable by calling setExpression(), and then evaluate it by calling validate(). This will cause any other variables that are dependent on it to be evaluated, and will also cause the container to be notified of the change, unlike setExpression().

Parameters:

expression - The expression.

Throws:

IllegalActionException - If this variable or a variable dependent on this variable cannot be evaluated (and is not lazy) and the model error handler throws an exception. Also thrown if the change is not acceptable to the container.

See Also:

getToken(), setExpression(String), validate()

setToken

public void setToken(Token token)
              throws IllegalActionException

Put a new token in this variable and notify the container and and value listeners. If an expression had been previously given using setExpression(), then that expression is forgotten. If the type of this variable has been set with setTypeEquals(), then convert the specified token into that type, if possible, or throw an exception, if not. If setTypeAtMost() has been called, then verify that its type constraint is satisfied, and if not, throw an exception.
Note that you can call this with a null argument regardless of type constraints, unless there are other variables that depend on its value.

Parameters:

token - The new token to be stored in this variable.

Throws:

IllegalActionException - If the token type is not compatible with specified constraints, or if you are attempting to set to null a variable that has value dependents, or if the container rejects the change.

See Also:

getToken()

setTypeAtLeast

public void setTypeAtLeast(InequalityTerm typeTerm)

Constrain the type of this variable to be equal to or greater than the type represented by the specified InequalityTerm. This constraint is not enforced here, but is returned by the typeConstraints() method for use by a type system.

Specified by:

setTypeAtLeast in interface Typeable

Parameters:

typeTerm - An InequalityTerm object.

setTypeAtLeast

public void setTypeAtLeast(Typeable lesser)

Constrain the type of this variable to be equal to or greater than the type of the specified object. This constraint is not enforced here, but is returned by the typeConstraints() method for use by a type system.

Specified by:

setTypeAtLeast in interface Typeable

Parameters:

lesser - A Typeable object.

setTypeAtMost

public void setTypeAtMost(Type type)
                   throws IllegalActionException

Set a type constraint that the type of this object be less than or equal to the specified class in the type lattice. This replaces any constraint specified by an earlier call to this same method (note that there is no point in having two separate specifications like this because it would be equivalent to a single specification using the greatest lower bound of the two). This is an absolute type constraint (not relative to another Typeable object), so it is checked every time the value of the variable is set by setToken() or by evaluating an expression. This type constraint is also returned by the typeConstraints() methods. To remove the type constraint, call this method with a BaseType.UNKNOWN argument.

Specified by:

setTypeAtMost in interface Typeable

Parameters:

type - An instance of Type.

Throws:

IllegalActionException - If the type of this object already violates this constraint, or if the argument is not an instantiable type in the type lattice.

setTypeEquals

public void setTypeEquals(Type type)
                   throws IllegalActionException

Set a type constraint that the type of this object equal the specified value. This is an absolute type constraint (not relative to another Typeable object), so it is checked every time the value of the variable is set by setToken() or by evaluating an expression. If the variable already has a value, then that value is converted to the specified type, if possible, or an exception is thrown. To remove the type constraint, call this method with the argument BaseType.UNKNOWN.

Specified by:

setTypeEquals in interface Typeable

Parameters:

type - A Type.

Throws:

IllegalActionException - If the type of this object already violates this constraint, in that the currently contained token cannot be converted losslessly to the specified type.

setTypeSameAs

public void setTypeSameAs(Typeable equal)

Constrain the type of this variable to be the same as the type of the specified object. This constraint is not enforced here, but is returned by the typeConstraints() method for use by a type system.

Specified by:

setTypeSameAs in interface Typeable

Parameters:

equal - A Typeable object.

setUnknown

public void setUnknown(boolean value)

Mark the value of this variable to be unknown if the argument is true, or known if the argument is false. In domains with fixed-point semantics, such as SR, a variable that depends on a port value may be unknown at various points during the execution.

Parameters:

value - True to change mark this variable unknown.

See Also:

isKnown()

setValueListenerAsWeakDependency

public void setValueListenerAsWeakDependency(ValueListener listener)

Set a value listener as a weak dependency. When this Variable changes containers, the value listener is not considered a dependency.

See Also:

setContainer(NamedObj)

setVisibility

public void setVisibility(Settable.Visibility visibility)

Set the visibility of this variable. The argument should be one of the public static instances in Settable.

Specified by:

setVisibility in interface Settable

Parameters:

visibility - The visibility of this variable.

See Also:

getVisibility()

stringRepresentation

@Deprecated
public java.lang.String stringRepresentation()

Deprecated.

Same as getExpression().

Returns:

A string representation of this variable.

toString

public java.lang.String toString()

Return a string representation of the current evaluated variable value.

Overrides:

toString in class NamedObj

Returns:

A string representing the class and the current token.

typeConstraints

public java.util.Set<Inequality> typeConstraints()

Return the type constraints of this variable. The constraints include the ones explicitly set to this variable, plus the constraint that the type of this variable must be no less than the type of its current value, if it has one. The constraints are a list of inequalities.

Specified by:

typeConstraints in interface HasTypeConstraints

Returns:

a list of Inequality objects.

See Also:

Inequality

typeConstraintList

@Deprecated
public java.util.List typeConstraintList()

Deprecated. Use typeConstraints().

Return the type constraints of this variable. The constraints include the ones explicitly set to this variable, plus the constraint that the type of this variable must be no less than its current type, if it has one. The constraints are a list of inequalities.

Returns:

a list of Inequality objects.

See Also:

Inequality

validate

public java.util.Collection validate()
                              throws IllegalActionException

If this variable is not lazy (the default) then evaluate the expression contained in this variable, and notify any value dependents. If those are not lazy, then they too will be evaluated. Also, if the variable is not lazy, then notify its container, if there is one, by calling its attributeChanged() method.

If this variable is lazy, then mark this variable and any of its value dependents as needing evaluation and for any value dependents that are not lazy, evaluate them. Note that if there are no value dependents, or if they are all lazy, then this will not result in evaluation of this variable, and hence will not ensure that the expression giving its value is valid. Call getToken() or getType() to accomplish that.

Specified by:

validate in interface Settable

Returns:

The current list of value listeners, which are evaluated as a consequence of this call to validate().

Throws:

IllegalActionException - If this variable or a variable dependent on this variable cannot be evaluated (and is not lazy) and the model error handler throws an exception. Also thrown if the change is not acceptable to the container.

valueChanged

public void valueChanged(Settable settable)

React to the change in the specified instance of Settable. Mark this variable as needing reevaluation when next accessed. Notify the value listeners of this variable.

Specified by:

valueChanged in interface ValueListener

Parameters:

settable - The object that has changed value.

_description

protected java.lang.String _description(int detail,
                                        int indent,
                                        int bracket)

Return a description of this variable. This returns the same information returned by toString(), but with optional indenting and brackets.

Overrides:

_description in class NamedObj

Parameters:

detail - The level of detail.

indent - The amount of indenting.

bracket - The number of surrounding brackets (0, 1, or 2).

Returns:

A string describing this variable.

_evaluate

protected void _evaluate()
                  throws IllegalActionException

Evaluate the current expression to a token. If this variable was last set directly with a token, then do nothing. In other words, the expression is evaluated only if the value of the token was most recently given by an expression. The expression is also evaluated if any of the variables it refers to have changed since the last evaluation. If the value of this variable changes due to this evaluation, then notify all value dependents and notify the container (if there is one) by calling its attributeChanged() and attributeTypeChanged() methods, as appropriate. An exception is thrown if the expression is illegal, for example if a parse error occurs or if there is a dependency loop.

If evaluation results in a token that is not of the same type as the current type of the variable, then the type of the variable is changed, unless the new type is incompatible with statically specified types (setTypeEquals() and setTypeAtMost()). If the type is changed, the attributeTypeChanged() method of the container is called. The container can reject the change by throwing an exception.

This method may trigger a model error, which is delegated up the container hierarchy until an error handler is found, and is ignored if no error handler is found. A model error occurs if the expression cannot be parsed or cannot be evaluated.

Part of this method is read-synchronized on the workspace.

Throws:

IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if a dependency loop is found.

_getCurrentExpression

protected java.lang.String _getCurrentExpression()

Get the current expression as a string, to be used to export to MoML.

Returns:

The current expression as a string.

_notifyValueListeners

protected void _notifyValueListeners()

Notify the value listeners of this variable that this variable changed.

_parseIfNecessary

protected final void _parseIfNecessary()
                                throws IllegalActionException

Parse the expression, if the current parse tree is not valid. This method should only be called if the expression is valid.

Throws:

IllegalActionException - If the exception cannot be parsed.

_propagate

protected java.util.List<IllegalActionException> _propagate()

Force evaluation of this variable, unless it is lazy, and call _propagate() on its value dependents.

Returns:

A list of instances of IllegalActionException, one for each exception triggered by a failure to evaluate a value dependent, or null if there were no failures.

_propagateToValueListeners

protected java.util.List<IllegalActionException> _propagateToValueListeners()

Call propagate() on all value listeners.

Returns:

A list of instances of IllegalActionException, one for each exception triggered by a failure to evaluate a value dependent, or null if there were no failures.

_propagateValue

protected void _propagateValue(NamedObj destination)
                        throws IllegalActionException

Propagate the value of this object to the specified object. The specified object is required to be an instance of the same class as this one, or a ClassCastException will be thrown.

Overrides:

_propagateValue in class NamedObj

Parameters:

destination - Object to which to propagate the value.

Throws:

IllegalActionException - If the value cannot be propagated.

_setToken

protected void _setToken(Token newToken)
                  throws IllegalActionException

Set the token value and type of the variable. If the type of the specified token is incompatible with specified absolute type constraints (i.e. those that can be checked), then throw an exception. It is converted to the type given by setTypeEquals() if necessary and possible. If the argument is null, then no type checks are done, and the contents of the variable is set to null.

Parameters:

newToken - The new value of the variable.

Throws:

IllegalActionException - If the token type is not compatible with specified constraints, or if you are attempting to set to null a variable that has value dependents.

_setTokenAndNotify

protected void _setTokenAndNotify(Token newToken)
                           throws IllegalActionException

Set the token value and type of the variable, and notify the container that the value (and type, if appropriate) has changed. Also notify value dependents that they need to be re-evaluated, and notify any listeners that have been registered with addValueListener(). If setTypeEquals() has been called, then attempt to convert the specified token into one of the appropriate type, if needed, rather than changing the type.

Parameters:

newToken - The new value of the variable.

Throws:

IllegalActionException - If the token type is not compatible with specified constraints, or if you are attempting to set to null a variable that has value dependents.