ptolemy.actor.parameters

Class PortParameter

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.kernel.util.AbstractSettableAttribute

ptolemy.data.expr.Variable

ptolemy.data.expr.Parameter

ptolemy.data.expr.AbstractInitializableParameter

ptolemy.actor.parameters.PortParameter

All Implemented Interfaces:

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

Direct Known Subclasses:

FilePortParameter, MirrorPortParameter

public class PortParameter
extends AbstractInitializableParameter
implements Initializable

This parameter creates an associated port that can be used to update the current value of the parameter. This parameter has two values, which may not be equal, a current value and a persistent value. The persistent value is returned by getExpression() and is set by any of three different mechanisms:

• calling setExpression();
• calling setToken(); and
• specifying a value as a constructor argument.

All three of these will also set the current value, which is then equal to the persistent value. The current value is returned by get getToken() and is set by any of two different mechanisms:

• calling setCurrentValue();
• calling update() sets the current value if there is an associated port, and that port has a token to consume; and

These two techniques do not change the persistent value, so after these are used, the persistent value and current value may be different.

When the container for this parameter is initialized, the current value of the parameter is reset to match the persistent value.

When using this parameter in an actor, care must be exercised to call update() exactly once per firing prior to calling getToken(). Each time update() is called, a new token will be consumed from the associated port (if the port is connected and has a token). If this is called multiple times in an iteration, it may result in consuming tokens that were intended for subsequent iterations. Thus, for example, update() should not be called in fire() and then again in postfire(). Moreover, in some domains (such as DE), it is essential that if a token is provided on a port, that it is consumed. In DE, the actor will be repeatedly fired until the token is consumed. Thus, it is an error to not call update() once per iteration. For an example of an actor that uses this mechanism, see Ramp.

If this actor is placed in a container that does not implement the TypedActor interface, then no associated port is created, and it functions as an ordinary parameter. This is useful, for example, if this is put in a library, where one would not want the associated port to appear.

There are a few situations where PortParameter might not do what you expect:

1. If it is used in a transparent composite actor, then a token provided to a PortParameter will never be read. A transparent composite actor is one without a director.
   Workaround: Put a director in the composite.
   
2. Certain actors (such as the Integrator in CT) read parameter values only during initialization. During initialization, a PortParameter can only have a value set via the parameter (it can't have yet received a token). So if the initial value of the Integrator is set to the value of the PortParameter, then it will see only the parameter value, never the value provided via the port.
   Workaround: Use a RunCompositeActor to contain the model with the Integrator.

Since:

Ptolemy II 3.0

Version:

$Id$

Author:

Edward A. Lee

See Also:

Ramp, ParameterPort

Pt.AcceptedRating:

Yellow (neuendor)

Pt.ProposedRating:

Green (eal)

Nested Class Summary

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

Variable.CircularDependencyError, 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

Fields

Modifier and Type	Field and Description
protected ParameterPort	_port The associated port.

Fields inherited from class ptolemy.data.expr.Variable

_currentExpression, _needsEvaluation, _parserScope, _parseTreeValid, _suppressVariableSubstitution, _valueListeners

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
	PortParameter(NamedObj container, java.lang.String name) Construct a parameter with the given name contained by the specified entity.
	PortParameter(NamedObj container, java.lang.String name, boolean initializeParameterPort) Construct a parameter with the given name contained by the specified entity.
protected	PortParameter(NamedObj container, java.lang.String name, ParameterPort port) Construct a parameter with the given name contained by the specified entity.
	PortParameter(NamedObj container, java.lang.String name, Token token) Construct a Parameter with the given container, name, and Token.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	_getCurrentExpression() Get the persistent expression as a string, to be used to export to MoML.
protected NamedObj	_propagateExistence(NamedObj container) Override the base class to also propagate the associated port.
protected void	_setTypeConstraints() Set the type constraints between the protected member _port and this parameter.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the parameter.
java.lang.String	getExpression() Get the persistent expression.
ParameterPort	getPort() Return the associated port.
void	initialize() Reset the current value to match the persistent value.
void	preinitialize() Reset the current value to match the persistent value.
void	setContainer(NamedObj entity) Set the container of this parameter.
void	setCurrentValue(Token token) Set the current value of this parameter and notify the container and value listeners.
void	setDisplayName(java.lang.String name) Set the display name, and propagate the name change to the associated port.
void	setExpression(java.lang.String expression) Override the base class to record the persistent expression.
void	setName(java.lang.String name) Set or change the name, and propagate the name change to the associated port.
void	setToken(Token newValue) Override the base class to record the persistent expression to be the string representation of the specified token.
boolean	update() Check to see whether a token has arrived at the associated port, and if so, update the current value of parameter with that token.

Methods inherited from class ptolemy.data.expr.AbstractInitializableParameter

_getInitializableContainer, addInitializable, hierarchyChanged, hierarchyWillChange, removeInitializable, wrapup

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, _propagateValue, _setToken, _setTokenAndNotify, addValueListener, getDeclaredType, getFreeIdentifiers, getParserScope, getScope, getScope, getToken, getType, getTypeTerm, getValueAsString, getVariable, getVisibility, invalidate, isKnown, isLazy, isStringMode, isSuppressVariableSubstitution, isTypeAcceptable, removeValueListener, reset, setLazy, setParseTreeEvaluator, setStringMode, setSuppressVariableSubstitution, setToken, setTypeAtLeast, setTypeAtLeast, setTypeAtMost, setTypeEquals, setTypeSameAs, setUnknown, setValueListenerAsWeakDependency, setVisibility, stringRepresentation, toString, typeConstraintList, typeConstraints, validate, valueChanged

Methods inherited from class ptolemy.kernel.util.AbstractSettableAttribute

getDefaultExpression

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, 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, 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, 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.actor.Initializable

addInitializable, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName

Methods inherited from interface ptolemy.kernel.util.Settable

getDisplayName

Field Detail

_port

protected ParameterPort _port

The associated port.

Constructor Detail

PortParameter

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

Construct a parameter with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This parameter will create an associated port in the same container.

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.

PortParameter

protected PortParameter(NamedObj container,
                        java.lang.String name,
                        ParameterPort port)
                 throws IllegalActionException,
                        NameDuplicationException

Construct a parameter with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This parameter will create an associated port in the same container.

Parameters:

container - The container.

name - The name of the parameter.

port - The associated ParameterPort, or null to create one.

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.

PortParameter

public PortParameter(NamedObj container,
                     java.lang.String name,
                     boolean initializeParameterPort)
              throws IllegalActionException,
                     NameDuplicationException

Construct a parameter with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This parameter will create an associated port in the same container.

Parameters:

container - The container.

name - The name of the parameter.

initializeParameterPort - True if the parameterPort should be initialized here. Some derived classes might want to initialize the port themselves (e.g. MirrorPortParameter).

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.

PortParameter

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

Construct a Parameter with the given container, name, and Token. The token defines the initial persistent and current values. The container argument must not be null, or a NullPointerException will be thrown. This parameter 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. The object is not added to the list of objects in the workspace unless the container is null. Increment the version of the workspace. If the name argument is null, then the name is set to the empty string.

Parameters:

container - The container.

name - The name.

token - The Token contained by this Parameter.

Throws:

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

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

Method Detail

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. In this class, if the attribute is an instance of Location, then the location of the associated port is set as well.

Overrides:

attributeChanged in class Variable

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

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

Clone the parameter. This overrides the base class to remove the current association with a port. It is assumed that the port will also be cloned, and when the containers are set of this parameter and that port, whichever one is set second will result in re-establishment of the association.

Overrides:

clone in class AbstractInitializableParameter

Parameters:

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

Returns:

The cloned parameter.

Throws:

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

See Also:

Object.clone()

getExpression

public java.lang.String getExpression()

Get the persistent expression.

Specified by:

getExpression in interface Settable

Overrides:

getExpression in class Variable

Returns:

The expression used by this variable.

See Also:

setExpression(String)

getPort

public ParameterPort getPort()

Return the associated port. Normally, there always is one, but if setContainer() is called to change the container, then this might return null. Also, during cloning, there is a transient during which this may return null.

Returns:

The associated port.

initialize

public void initialize()
                throws IllegalActionException

Reset the current value to match the persistent value.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AbstractInitializableParameter

Throws:

IllegalActionException - If thrown by a subclass.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Reset the current value to match the persistent value.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AbstractInitializableParameter

Throws:

IllegalActionException - If thrown by a subclass.

setContainer

public void setContainer(NamedObj entity)
                  throws IllegalActionException,
                         NameDuplicationException

Set the container of this parameter. If the container is different from what it was before and there is an associated port, then also change the container of the port.

Overrides:

setContainer in class AbstractInitializableParameter

Parameters:

entity - The new container.

Throws:

IllegalActionException - If the superclass throws it.

NameDuplicationException - If the superclass throws it.

See Also:

ParameterPort

setCurrentValue

public void setCurrentValue(Token token)
                     throws IllegalActionException

Set the current value of this parameter and notify the container and value listeners. This does not change the persistent value (returned by getExpression()), but does change the current value (returned by getToken()).

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.

setDisplayName

public void setDisplayName(java.lang.String name)

Set the display name, and propagate the name change to the associated port. Increment the version of the workspace. This method is write-synchronized on the workspace.

Overrides:

setDisplayName in class NamedObj

Parameters:

name - The new display name.

See Also:

NamedObj.getDisplayName()

setExpression

public void setExpression(java.lang.String expression)

Override the base class to record the persistent expression.

Specified by:

setExpression in interface Settable

Overrides:

setExpression in class Variable

Parameters:

expression - The expression for this variable.

See Also:

getExpression()

setName

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

Set or change the name, and propagate the name change to the associated port. If a null argument is given, then the name is set to an empty string. Increment the version of the workspace. This method is write-synchronized on the workspace.

Specified by:

setName in interface Nameable

Overrides:

setName in class Variable

Parameters:

name - The new name.

Throws:

IllegalActionException - If the name contains a period.

NameDuplicationException - If the container already contains an attribute with the proposed name.

See Also:

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

setToken

public void setToken(Token newValue)
              throws IllegalActionException

Override the base class to record the persistent expression to be the string representation of the specified token.

Overrides:

setToken in class Variable

Parameters:

newValue - The new persistent value.

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:

Variable.getToken()

update

public boolean update()
               throws IllegalActionException

Check to see whether a token has arrived at the associated port, and if so, update the current value of parameter with that token. If there is no associated port, do nothing.

Returns:

True if an input token has been consumed, false if not.

Throws:

IllegalActionException - If reading from the associated port throws it.

_getCurrentExpression

protected java.lang.String _getCurrentExpression()

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

Overrides:

_getCurrentExpression in class Variable

Returns:

The persistent expression as a string.

_propagateExistence

protected NamedObj _propagateExistence(NamedObj container)
                                throws IllegalActionException

Override the base class to also propagate the associated port.

Overrides:

_propagateExistence in class Attribute

Parameters:

container - Object to contain the new object.

Returns:

A new object of the same class and name as this one.

Throws:

IllegalActionException - If the object cannot be cloned.

_setTypeConstraints

protected void _setTypeConstraints()

Set the type constraints between the protected member _port and this parameter. This is a protected method so that subclasses can define different type constraints.