ptolemy.actor.lib
Class SetVariable

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.actor.lib.SetVariable
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, ptolemy.kernel.util.ChangeListener, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.actor.util.ExplicitChangeContext, ptolemy.kernel.util.Instantiable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.actor.TypedActor

public class SetVariable
extends ptolemy.actor.TypedAtomicActor
implements ptolemy.kernel.util.ChangeListener, ptolemy.actor.util.ExplicitChangeContext

Set the value of a variable contained by the container. The change to the value of the variable is implemented in a change request, and consequently will not take hold until the end of the current iteration. This helps ensure that users of value of the variable will see changes to the value deterministically (independent of the schedule of execution of the actors).

Note that the variable name is observed during preinitialize(). If it is changed after that, the change will not take effect until the next time the model is executed. Moreover, the type of the variable is constrained in preinitialize() to be at least that of the input port for this actor.

The variable can be either any attribute that implements the Settable interface. If it is in addition an instance of Variable, then the input token is used directly to set the value, and the type of the variable is constrained to be the same as the type of the input. Otherwise, then input token is converted to a string and the setExpression() method on the variable is used to set the value.

Since:
Ptolemy II 4.0
Version:
$Id: SetVariable.java,v 1.18 2004/04/19 05:07:40 eal Exp $
Author:
Edward A. Lee, Steve Neuendorffer
See Also:
Serialized Form
Accepted Rating:
Red (cxh)
Proposed Rating:
Red (yuhong)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
 ptolemy.actor.TypedIOPort input
          The input port.
 ptolemy.kernel.util.StringAttribute variableName
          The name of the variable in the container to set.
 
Fields inherited from class ptolemy.actor.AtomicActor
_stopRequested
 
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.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
SetVariable(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void changeExecuted(ptolemy.kernel.util.ChangeRequest change)
          Do nothing.
 void changeFailed(ptolemy.kernel.util.ChangeRequest change, java.lang.Exception exception)
          React to the fact that a change failed by setting a flag that causes an exception to be thrown in next call to prefire() or wrapup().
 ptolemy.kernel.Entity getContext()
          Return the change context being made explicit.
 ptolemy.kernel.util.Attribute getModifiedVariable()
          Return the (presumably Settable) attribute modified by this actor.
 java.util.List getModifiedVariables()
          Return a list of variables that this entity modifies.
 boolean postfire()
          Read at most one token from the input port and issue a change request to update variables as indicated by the input.
 void preinitialize()
          If there is no variable with the specified name, then create one.
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, iterate, newReceiver, outputPortList, prefire, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, 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, setName
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
fire, initialize, iterate, prefire, stop, stopFire, terminate, wrapup
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 

Field Detail

input

public ptolemy.actor.TypedIOPort input
The input port.


variableName

public ptolemy.kernel.util.StringAttribute variableName
The name of the variable in the container to set.

Constructor Detail

SetVariable

public SetVariable(ptolemy.kernel.CompositeEntity container,
                   java.lang.String name)
            throws ptolemy.kernel.util.NameDuplicationException,
                   ptolemy.kernel.util.IllegalActionException
Construct an actor with the given container and name.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If this actor cannot be contained by the proposed container.
ptolemy.kernel.util.NameDuplicationException - If the container already has an actor with this name.
Method Detail

changeExecuted

public void changeExecuted(ptolemy.kernel.util.ChangeRequest change)
Do nothing.

Specified by:
changeExecuted in interface ptolemy.kernel.util.ChangeListener
Parameters:
change - The change that executed.

changeFailed

public void changeFailed(ptolemy.kernel.util.ChangeRequest change,
                         java.lang.Exception exception)
React to the fact that a change failed by setting a flag that causes an exception to be thrown in next call to prefire() or wrapup().

Specified by:
changeFailed in interface ptolemy.kernel.util.ChangeListener
Parameters:
change - The change request.
exception - The exception that resulted.

getContext

public ptolemy.kernel.Entity getContext()
Return the change context being made explicit. In this case, the change context returned is this actor.

Specified by:
getContext in interface ptolemy.actor.util.ExplicitChangeContext

getModifiedVariable

public ptolemy.kernel.util.Attribute getModifiedVariable()
                                                  throws ptolemy.kernel.util.IllegalActionException
Return the (presumably Settable) attribute modified by this actor. This is the attribute in the container of this actor with the name given by the variableName attribute. If no such attribute is found, then this method creates a new variable in the actor's container with the correct name. This method gets write access on the workspace.

Throws:
ptolemy.kernel.util.IllegalActionException - If the variable cannot be found.

getModifiedVariables

public java.util.List getModifiedVariables()
                                    throws ptolemy.kernel.util.IllegalActionException
Return a list of variables that this entity modifies. The variables are assumed to have a change context of the given entity.

Specified by:
getModifiedVariables in interface ptolemy.actor.util.ExplicitChangeContext
Returns:
A list of variables.
Throws:
ptolemy.kernel.util.IllegalActionException - If the list of modified variables cannot be returned.

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
Read at most one token from the input port and issue a change request to update variables as indicated by the input.

Specified by:
postfire in interface ptolemy.actor.Executable
Throws:
ptolemy.kernel.util.IllegalActionException - If thrown reading the input.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.IllegalActionException
If there is no variable with the specified name, then create one. This is done in preinitialize() so that we can set up a type constraint that ensures that the type of the variable is at least that of the input port.

Specified by:
preinitialize in interface ptolemy.actor.Executable
Throws:
ptolemy.kernel.util.IllegalActionException - If the superclass throws it, or if there is no container.