ptolemy.actor.parameters
Class PortParameter

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.kernel.util.AbstractSettableAttribute
              extended byptolemy.data.expr.Variable
                  extended byptolemy.data.expr.Parameter
                      extended byptolemy.actor.parameters.PortParameter
All Implemented Interfaces:
ptolemy.kernel.util.Changeable, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.data.type.HasTypeConstraints, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.kernel.util.Settable, ptolemy.data.type.Typeable, ptolemy.kernel.util.ValueListener

public class PortParameter
extends ptolemy.data.expr.Parameter

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:

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 three different mechanisms: These three techniques do not change the persistent value, so after these are used, the persistent value and current value may be different.

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.

Since:
Ptolemy II 3.0
Version:
$Id: PortParameter.java,v 1.28.2.1 2004/06/18 00:48:59 cxh Exp $
Author:
Edward A. Lee
See Also:
Ramp, ParameterPort, Serialized Form
Accepted Rating:
Yellow (neuendor)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.data.expr.Variable
ptolemy.data.expr.Variable.VariableScope
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
ptolemy.kernel.util.NamedObj.ContainedObjectsIterator
 
Nested classes inherited from class ptolemy.kernel.util.Settable
ptolemy.kernel.util.Settable.Visibility
 
Field Summary
protected  ParameterPort _port
          The associated port.
 
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, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.kernel.util.Settable
EXPERT, FULL, NONE, NOT_EDITABLE
 
Constructor Summary
PortParameter(ptolemy.kernel.util.NamedObj container, java.lang.String name)
          Construct a parameter with the given name contained by the specified entity.
PortParameter(ptolemy.kernel.util.NamedObj container, java.lang.String name, ptolemy.data.Token token)
          Construct a Parameter with the given container, name, and Token.
 
Method Summary
protected  void _checkContainer(ptolemy.kernel.Entity container)
          Check that the specified container is of a suitable class for this parameter.
 void attributeChanged(ptolemy.kernel.util.Attribute attribute)
          React to a change in an attribute.
 java.lang.Object clone(ptolemy.kernel.util.Workspace workspace)
          Clone the parameter.
 ParameterPort getPort()
          Return the associated port.
 void setContainer(ptolemy.kernel.Entity entity)
          Set the container of this parameter.
 void setCurrentValue(ptolemy.data.Token token)
          Set the current value of this parameter and notify the container and value listeners.
 void setName(java.lang.String name)
          Set or change the name, and propagate the name change to the associated port.
 void 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.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, getExpression, getFreeIdentifiers, getScope, getToken, getType, getTypeTerm, getVisibility, invalidate, isKnown, isLazy, isStringMode, isTypeAcceptable, removeValueListener, reset, setContainer, setExpression, setLazy, setParseTreeEvaluator, setStringMode, setToken, setToken, setTypeAtLeast, setTypeAtLeast, setTypeAtMost, setTypeEquals, setTypeSameAs, setUnknown, setVisibility, stringRepresentation, toString, typeConstraintList, validate, valueChanged
 
Methods inherited from class ptolemy.kernel.util.AbstractSettableAttribute
getDefaultExpression
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, getContainer
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, 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.Nameable
description, getContainer, getFullName, getName, getName
 

Field Detail

_port

protected ParameterPort _port
The associated port.

Constructor Detail

PortParameter

public PortParameter(ptolemy.kernel.util.NamedObj container,
                     java.lang.String name)
              throws ptolemy.kernel.util.IllegalActionException,
                     ptolemy.kernel.util.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:
ptolemy.kernel.util.IllegalActionException - If the parameter is not of an acceptable class for the container.
ptolemy.kernel.util.NameDuplicationException - If the name coincides with a parameter already in the container.

PortParameter

public PortParameter(ptolemy.kernel.util.NamedObj container,
                     java.lang.String name,
                     ptolemy.data.Token token)
              throws ptolemy.kernel.util.IllegalActionException,
                     ptolemy.kernel.util.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:
ptolemy.kernel.util.IllegalActionException - If the parameter is not of an acceptable class for the container.
ptolemy.kernel.util.NameDuplicationException - If the name coincides with an parameter already in the container.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.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.

Parameters:
attribute - The attribute that changed.
Throws:
ptolemy.kernel.util.IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

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.

clone

public java.lang.Object clone(ptolemy.kernel.util.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.

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

setContainer

public void setContainer(ptolemy.kernel.Entity entity)
                  throws ptolemy.kernel.util.IllegalActionException,
                         ptolemy.kernel.util.NameDuplicationException
Set the container of this parameter. If the container is different from what it was before and there is an associated port, then break the association. If the new container has a port with the same name as this parameter, then establish a new association. That port must be an instance of ParameterPort, or no association is created.

Parameters:
entity - The new container.
Throws:
ptolemy.kernel.util.IllegalActionException - If the superclass throws it.
ptolemy.kernel.util.NameDuplicationException - If the superclass throws it.
See Also:
ParameterPort

setCurrentValue

public void setCurrentValue(ptolemy.data.Token token)
                     throws ptolemy.kernel.util.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:
ptolemy.kernel.util.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.

setName

public void setName(java.lang.String name)
             throws ptolemy.kernel.util.IllegalActionException,
                    ptolemy.kernel.util.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.

Parameters:
name - The new name.
Throws:
ptolemy.kernel.util.IllegalActionException - If the name contains a period.
ptolemy.kernel.util.NameDuplicationException - If the container already contains an attribute with the proposed name.

update

public void update()
            throws ptolemy.kernel.util.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.

Throws:
ptolemy.kernel.util.IllegalActionException - If reading from the associated port throws it.

_checkContainer

protected void _checkContainer(ptolemy.kernel.Entity container)
                        throws ptolemy.kernel.util.IllegalActionException
Check that the specified container is of a suitable class for this parameter.

Parameters:
container - The proposed container.
Throws:
ptolemy.kernel.util.IllegalActionException - If the container is not an instance of Entity.