ptolemy.actor.parameters
Class SharedParameter

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.kernel.util.AbstractSettableAttribute
              ptolemy.data.expr.Variable
                  ptolemy.data.expr.Parameter
                      ptolemy.actor.parameters.SharedParameter

All Implemented Interfaces:

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

Direct Known Subclasses:

PtinyOSNodeParameter

public class SharedParameter
extends Parameter
implements Initializable

This parameter is shared throughout a model. Changing the expression of any one instance of the parameter will result in all instances that are shared being changed to the same expression. An instance elsewhere in the model (within the same top level) is shared if it has the same name and its container is of the class specified in the constructor (or of the container class, if no class is specified in the constructor). Note that two parameters with the same expression do not necessarily have the same value, since the expression may reference other parameters that are in scope.

One exception is that if this parameter is (deeply) within an instance of EntityLibrary, then the parameter is not shared. Were this not the case, then opening a library containing this parameter would force expansion of all the sublibraries of EntityLibrary, which would defeat the lazy instantiation of EntityLibrary.

When this parameter is constructed, the specified container will be used to infer the parameter value from the container. That is, if the container is within a model that has any parameters shared with this one, then the value will be set to the last of those encountered. If the container is subsequently changed, it is up to the code implementing the change to use the inferValueFromContext() method to reset the value to match the new context. Note that this really needs to be done if the container of the container, or its container, or any container above this parameter is changed. It is recommended to use the four-argument constructor, so you can specify a default value to use if there are no shared parameters.

Note that it might be tempting to use a static parameter field to achieve this effect, but this would be problematic for two reasons. First, the parameter would only be able to have one container. Second, the parameter would be shared across all models in the same Java virtual machine, not just within a single model.

Since:

Ptolemy II 8.0

Version:

$Id: SharedParameter.java 57044 2010-01-27 22:41:05Z cxh $

Author:

Edward A. Lee, contributor: Christopher Brooks, Bert Rodiers

See Also:

Serialized Form

Accepted Rating:

Green (acataldo)

Proposed Rating:

Green (eal)

Nested Class Summary

private static class

SharedParameter.SharedParameterRegistry Registry of shared parameters.

Nested classes/interfaces inherited from class ptolemy.data.expr.Variable

Variable.VariableScope

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

private boolean	_constructionFinished Indicator that the constructor has reached the end.
private java.lang.Class	_containerClass The container class.
private static boolean	_delayValidation True if we are delaying validation.
private static java.util.Collection<java.lang.ref.WeakReference<SharedParameter>>	_EMPTY_LIST Empty list.
private java.util.List<Initializable>	_initializables List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
private static java.util.List<SharedParameter.SharedParameterRegistry>	_REGISTRY Registry by workspace.
private SharedParameter	_sharedParameter Cached version of a shared parameter.
private java.util.HashSet<SharedParameter>	_sharedParameterSet Cached version of the shared parameter set.
private long	_sharedParameterSetVersion Version for the cache.
private long	_sharedParameterVersion Version for the cache.
private boolean	_suppressingPropagation Indicator to suppress propagation.

Fields inherited from class ptolemy.data.expr.Variable

_currentExpression, _needsEvaluation, _parserScope, _parseTreeValid, _valueListeners

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _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

SharedParameter(NamedObj container, java.lang.String name)
Construct a parameter with the given container and name.

SharedParameter(NamedObj container, java.lang.String name, java.lang.Class containerClass)
Construct a parameter with the given container, name, and container class.

SharedParameter(NamedObj container, java.lang.String name, java.lang.Class containerClass, java.lang.String defaultValue)
Construct a parameter with the given container, name, container class, and default value.

Method Summary

private SharedParameter	_getOneSharedParameter(NamedObj container) Find and return one shared parameter deeply contained by the specified container.
private static SharedParameter.SharedParameterRegistry	_getSharedParameterRegistry(Workspace workspace) Return the shared parameter registry associated with this workspace.
protected void	_propagateValue(NamedObj destination) Override the base class to do the propagation only if the specified destination is not shared, because if it is shared, then the value will be propagated in through the sharing mechanism.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
java.lang.Object	clone(Workspace workspace) Override the base class to register the object, since setName() will not be called.
NamedObj	getRoot() Return the top level of the containment hierarchy, unless one of the containers is an instance of EntityLibrary, in which case, return null.
Token	getToken() Get the token contained by this variable.
void	inferValueFromContext(java.lang.String defaultValue) Infer the value of this parameter from the container context.
void	initialize() Do nothing except invoke the initialize methods of objects that have been added using addInitializable().
boolean	isFireFunctional() Return true.
boolean	isStrict() Return false.
boolean	isSuppressingPropagation() Return true if this instance is suppressing propagation.
void	preinitialize() Traverse the model and update values.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	setContainer(NamedObj container) Override the base class to register as an initializable slave with the new container.
void	setExpression(java.lang.String expression) Override the base class to also set the expression of shared parameters.
void	setName(java.lang.String name) Override the base class to register as a shared parameter in the workspace.
void	setSuppressingPropagation(boolean propagation) Specify whether this instance should be suppressing propagation.
void	setToken(Token token) Override the base class to also set the token of shared parameters.
java.util.Collection	sharedParameterSet() Return a collection of all the shared parameters within the same model as this parameter.
java.util.Collection	validate() Override the base class to also validate the shared instances.
void	wrapup() Supress propagation.

Methods inherited from class ptolemy.data.expr.Parameter

addChoice, exportMoML, getChoices, removeAllChoices, removeChoice

Methods inherited from class ptolemy.data.expr.Variable

_description, _evaluate, _notifyValueListeners, _parseIfNecessary, _propagate, _propagateToValueListeners, _setToken, _setTokenAndNotify, addValueListener, getDeclaredType, getExpression, getFreeIdentifiers, getParserScope, getScope, getScope, getType, getTypeTerm, getValueAsString, getVariable, getVisibility, invalidate, isKnown, isLazy, isStringMode, isTypeAcceptable, removeValueListener, reset, setLazy, setParseTreeEvaluator, setStringMode, setToken, setTypeAtLeast, setTypeAtLeast, setTypeAtMost, setTypeEquals, setTypeSameAs, setUnknown, setVisibility, stringRepresentation, toString, typeConstraintList, typeConstraints, valueChanged

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, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, 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, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, 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

_constructionFinished

private boolean _constructionFinished

Indicator that the constructor has reached the end.

_containerClass

private java.lang.Class _containerClass

The container class.

_delayValidation

private static final boolean _delayValidation

True if we are delaying validation. FIXME: This variable is only present for testing and development. To try out the delay of validation, set it to true and recompile.

See Also:

Constant Field Values

_EMPTY_LIST

private static java.util.Collection<java.lang.ref.WeakReference<SharedParameter>> _EMPTY_LIST

Empty list.

_initializables

private transient java.util.List<Initializable> _initializables

List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

_sharedParameter

private SharedParameter _sharedParameter

Cached version of a shared parameter.

_sharedParameterVersion

private long _sharedParameterVersion

Version for the cache.

_sharedParameterSet

private java.util.HashSet<SharedParameter> _sharedParameterSet

Cached version of the shared parameter set.

_sharedParameterSetVersion

private long _sharedParameterSetVersion

Version for the cache.

_REGISTRY

private static java.util.List<SharedParameter.SharedParameterRegistry> _REGISTRY

Registry by workspace.

_suppressingPropagation

private boolean _suppressingPropagation

Indicator to suppress propagation.

Constructor Detail

SharedParameter

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

Construct a parameter with the given container and name. The container class will be used to determine which other instances of SharedParameter are shared with this one.

Parameters:

container - The container.

name - The name of the parameter.

Throws:

IllegalActionException - If the parameter is not of an acceptable class for the container.

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

SharedParameter

public SharedParameter(NamedObj container,
                       java.lang.String name,
                       java.lang.Class containerClass)
                throws IllegalActionException,
                       NameDuplicationException

Construct a parameter with the given container, name, and container class. The specified class will be used to determine which other instances of SharedParameter are shared with this one.

Parameters:

container - The container.

name - The name of the parameter.

containerClass - The class used to determine shared instances.

Throws:

IllegalActionException - If the parameter is not of an acceptable class for the container.

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

SharedParameter

public SharedParameter(NamedObj container,
                       java.lang.String name,
                       java.lang.Class containerClass,
                       java.lang.String defaultValue)
                throws IllegalActionException,
                       NameDuplicationException

Construct a parameter with the given container, name, container class, and default value. This is the preferred constructor to use. The specified class will be used to determine which other instances of SharedParameter are shared with this one.

Parameters:

container - The container.

name - The name of the parameter.

containerClass - The class used to determine shared instances. An argument of null means simply to use the class of the container, whatever that happens to be.

defaultValue - The default value to use if the container's model has no shared parameters.

Throws:

IllegalActionException - If the parameter is not of an acceptable class for the container, or an empty string to specify no default value.

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

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable), CompositeActor.addPiggyback(Executable)

clone

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

Override the base class to register the object, since setName() will not be called.

Overrides:

clone in class Variable

Parameters:

workspace - The workspace for the new object.

Returns:

A new NamedObj.

Throws:

java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.

See Also:

Parameter.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

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.

Overrides:

getToken in class Variable

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(Token)

getRoot

public NamedObj getRoot()

Return the top level of the containment hierarchy, unless one of the containers is an instance of EntityLibrary, in which case, return null.

Returns:

The top level, or null if this is within a library.

inferValueFromContext

public void inferValueFromContext(java.lang.String defaultValue)

Infer the value of this parameter from the container context. That is, search for parameters that are shared with this one, and set the value of this parameter to match the first one encountered. If there are no shared parameters, then assign the default value given as an argument.

Parameters:

defaultValue - The default parameter value to use.

initialize

public void initialize()
                throws IllegalActionException

Do nothing except invoke the initialize methods of objects that have been added using addInitializable().

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If one of the added objects throws it.

isFireFunctional

public boolean isFireFunctional()

Return true.

Returns:

True.

isStrict

public boolean isStrict()

Return false.

Returns:

False.

isSuppressingPropagation

public boolean isSuppressingPropagation()

Return true if this instance is suppressing propagation. Unless setSuppressingPropagation() has been called, this returns false.

Returns:

Returns whether this instance is suppressing propagation.

See Also:

setSuppressingPropagation(boolean)

preinitialize

public void preinitialize()
                   throws IllegalActionException

Traverse the model and update values.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - Not thrown in this base class.

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable), CompositeActor.removePiggyback(Executable)

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to register as an initializable slave with the new container. This results in the preinitialize(), initialize(), and wrapup() methods of this instance being invoked when the corresponding method of the container are invoked.

Overrides:

setContainer in class Variable

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace.

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

See Also:

Attribute.getContainer()

setName

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

Override the base class to register as a shared parameter in the workspace.

Specified by:

setName in interface Nameable

Overrides:

setName in class Variable

Parameters:

name - The proposed 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)

setExpression

public void setExpression(java.lang.String expression)

Override the base class to also set the expression of shared parameters.

Specified by:

setExpression in interface Settable

Overrides:

setExpression in class Variable

Parameters:

expression - The expression.

See Also:

Variable.getExpression()

setSuppressingPropagation

public void setSuppressingPropagation(boolean propagation)

Specify whether this instance should be suppressing propagation. If this is called with value true, then changes to this parameter will not propagate to other shared instances in the model.

Parameters:

propagation - True to suppress propagation.

See Also:

isSuppressingPropagation()

setToken

public void setToken(Token token)
              throws IllegalActionException

Override the base class to also set the token of shared parameters.

Overrides:

setToken in class Variable

Parameters:

token - The token.

Throws:

IllegalActionException - Thrown if super class throws it.

See Also:

getToken()

sharedParameterSet

public java.util.Collection sharedParameterSet()

Return a collection of all the shared parameters within the same model as this parameter. If there are no such parameters or if this parameter is deeply contained within an EntityLibrary, then return an empty collection. Otherwise, the list will include this instance if this instance has a container. If this instance has no container, then return an empty collection. A shared parameter is one that is an instance of SharedParameter, has the same name as this one, and is contained by the container class specified in the constructor.

Returns:

A collection of parameters.

wrapup

public void wrapup()
            throws IllegalActionException

Supress propagation.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - Not thrown in this base class.

validate

public java.util.Collection validate()
                              throws IllegalActionException

Override the base class to also validate the shared instances.

Specified by:

validate in interface Settable

Overrides:

validate in class Variable

Returns:

A Collection of all the shared parameters within the same model as this parameter, see sharedParameterSet().

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.

_propagateValue

protected void _propagateValue(NamedObj destination)
                        throws IllegalActionException

Override the base class to do the propagation only if the specified destination is not shared, because if it is shared, then the value will be propagated in through the sharing mechanism.

Overrides:

_propagateValue in class Variable

Parameters:

destination - Object to which to propagate the value.

Throws:

IllegalActionException - If the value cannot be propagated.

_getOneSharedParameter

private SharedParameter _getOneSharedParameter(NamedObj container)

Find and return one shared parameter deeply contained by the specified container. If there is no such parameter, then return null. A shared parameter is one that is an instance of SharedParameter, has the same name as this one, and is contained by the container class specified in the constructor.

Parameters:

container - The container.

Returns:

A shared parameter different from this one, or null if there is none.

_getSharedParameterRegistry

private static SharedParameter.SharedParameterRegistry _getSharedParameterRegistry(Workspace workspace)

Return the shared parameter registry associated with this workspace.