ptolemy.actor.ptalon
Class PtalonActor

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.actor.CompositeActor
                          ptolemy.actor.TypedCompositeActor
                              ptolemy.actor.ptalon.PtalonActor

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

PtalonMatcher.NestedPtalonActor

public class PtalonActor
extends TypedCompositeActor
implements Configurable

An aggregation of typed actors, specified by a Ptalon program.

A TypedCompositeActor is an aggregation of typed actors. A PtalonActor is a TypedCompositeActor whose aggregation is specified by a Ptalon program in an external file. This file is loaded during initialization, and is specified in a FileParameter called ptalonCodeLocation.

Since:

Ptolemy II 6.1

Version:

$Id: PtalonActor.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Adam Cataldo, Elaine Cheong, Contributor: Christopher Brooks

See Also:

Serialized Form

Accepted Rating:

Yellow (celaine)

Proposed Rating:

Yellow (celaine)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.CompositeEntity

CompositeEntity.ContainedObjectsIterator

Field Summary

private java.util.List<PtalonParameter>	_assignedPtalonParameters A list of all ptalon parameters that have been assigned a value.
private java.util.Hashtable<java.lang.String,PtalonParameter>	_assignedPtalonParametersCopy A table of copies of all the elements in _assignedPtalonParameters.
private java.util.Hashtable<java.lang.String,Token>	_assignedPtalonParametersCopyValues A table of copies of token values of all of the elements in _assignedPtalonParameters.
private PtalonAST	_ast The abstract syntax tree for the PtalonActor.
private boolean	_astCreated A boolean whose value is true if the AST has been created.
private PtalonEvaluator	_codeManager Information generated about the Ptalon code that is used by the compiler.
private java.lang.String	_configureSource The text representation of the URL for this object.
private int	_nestedDepth The depth for this actor with respect to nested actor declarations.
private java.util.List<PtalonParameter>	_ptalonParameters The list of all ptalon parameters for this actor.
private java.util.List<PtalonParameter>	_unsettablePtalonParameters The list of all ptalon parameters who are not settable by the user.
FileParameter	ptalonCodeLocation The location of the Ptalon code.

Fields inherited from class ptolemy.actor.CompositeActor

_actorFiringListeners, _causalityInterface, _initializables, _notifyingActorFiring, _publishedPorts, _publisherRelations, _stopRequested

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

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.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

PtalonActor(CompositeEntity container, java.lang.String name)
Construct a PtalonActor with a name and a container.

Method Summary

protected void	_addAttribute(Attribute attribute) Add the attribute, and if the attribute is a PtalonParameter, add it to a list of Ptalon parameters.
protected PtalonEvaluator	_createPtalonEvaluator(PtalonActor actor)
protected PtalonPopulator	_createPtalonPopulator()
protected PtalonRecognizer	_createPtalonRecognizer(PtalonLexer lexer) Create Ptalon parser.
protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object, which in this class is the configuration information.
protected void	_initializePtalonActor() Initialize this PtalonActor.
protected void	_initializePtalonCodeLocation() This helper method is used to begin the Ptalon compiler if the ptalonCodeLocation attribute has been updated.
private boolean	_isValueChanged(PtalonParameter p) Return true if the value of the given PtalonParameter has changed.
protected void	_removeContents()
void	attributeChanged(Attribute attribute) React to a change in an attribute.
void	configure(java.net.URL base, java.lang.String source, java.lang.String text) Read the saved XML for this PtalonActor.
java.lang.String	getConfigureSource() Return the input source that was specified the last time the configure() method was called.
java.lang.String	getConfigureText() Override the default behavior to always return null.
java.lang.String	getMappedName(java.lang.String ptalonName) Get the stored unique name for a symbol in the PtalonActor.
int	getNestedDepth() Return the depth of this PtalonActor declaration with respect to its creator.
PtalonParameter	getPtalonParameter(java.lang.String name) Find the parameter in the Ptalon code with the specified name, and return the Ptolemy parameter (java) that was created.
void	setNestedDepth(int depth) Set the depth of this PtalonActor declaration with respect to its creator.
java.lang.String	uniqueName(java.lang.String prefix) Return a name that is guaranteed to not be the name of any contained attribute, port, class, entity, or relation.

Methods inherited from class ptolemy.actor.TypedCompositeActor

_addEntity, _addPort, _addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newPort, newRelation, resolveTypes, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.CompositeActor

_actorFiring, _actorFiring, _finishedAddEntity, _getPublishedPort, _setDirector, addActorFiringListener, addInitializable, addPiggyback, clone, connectionsChanged, createReceivers, createSchedule, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inferringWidths, inferWidths, initialize, inputPortList, isFireFunctional, isOpaque, isStrict, iterate, linkToPublishedPort, linkToPublishedPort, needsWidthInference, newInsideReceiver, newReceiver, notifyConnectivityChange, outputPortList, postfire, prefire, preinitialize, recordFiring, registerPublisherPort, removeActorFiringListener, removeInitializable, removePiggyback, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate, unlinkToPublishedPort, unlinkToPublishedPort, unregisterPublisherPort, wrapup

Methods inherited from class ptolemy.kernel.CompositeEntity

_adjustDeferrals, _deepOpaqueEntityList, _description, _recordDecoratedAttributes, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, statistics

Methods inherited from class ptolemy.kernel.ComponentEntity

_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

ptalonCodeLocation

public FileParameter ptalonCodeLocation

The location of the Ptalon code.

_assignedPtalonParameters

private java.util.List<PtalonParameter> _assignedPtalonParameters

A list of all ptalon parameters that have been assigned a value. This is a subset of _ptalonParameters.

_assignedPtalonParametersCopy

private java.util.Hashtable<java.lang.String,PtalonParameter> _assignedPtalonParametersCopy

A table of copies of all the elements in _assignedPtalonParameters. In each entry of this table, the value is a copy of an element in _assignedPtalonParameters (a PtalonParameter) and the key is the name returned by getName(). This table is used to compare newly assigned expression values against previously assigned expression values.

_assignedPtalonParametersCopyValues

private java.util.Hashtable<java.lang.String,Token> _assignedPtalonParametersCopyValues

A table of copies of token values of all of the elements in _assignedPtalonParameters. In each entry of this table, the value is the token value of an element in _assignedPtalonParameters (a PtalonParameter) and the key is the name returned by getName(). This table is used to compare current token values against previous token values.

_ast

private PtalonAST _ast

The abstract syntax tree for the PtalonActor.

_astCreated

private boolean _astCreated

A boolean whose value is true if the AST has been created.

_codeManager

private PtalonEvaluator _codeManager

Information generated about the Ptalon code that is used by the compiler.

_configureSource

private java.lang.String _configureSource

The text representation of the URL for this object.

_nestedDepth

private int _nestedDepth

The depth for this actor with respect to nested actor declarations.

_ptalonParameters

private java.util.List<PtalonParameter> _ptalonParameters

The list of all ptalon parameters for this actor.

_unsettablePtalonParameters

private java.util.List<PtalonParameter> _unsettablePtalonParameters

The list of all ptalon parameters who are not settable by the user. This is a subset of _ptalonParameters.

Constructor Detail

PtalonActor

public PtalonActor(CompositeEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException

Construct a PtalonActor with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This actor 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. This actor will have no local director initially, and its executive director will be simply the director of the container.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor 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. This initially responds to changes in the ptalonCodeLocation parameter by calling a method which starts the parsing of the Ptalon code. Later, this method responds to changes in parameters specified in the Ptalon code itself: (1) If the parameter was not previously assigned, then update the internal variables; (2) If the parameter was previously assigned, then update the internal variables, and also update the rest of the PtalonActor based on the new value of the parameter (we currently choose the reparse and regenerate the entire PtalonActor from scratch).

We choose to implement this in attributeChanged() instead if preinitialize() because we want changes to be reflected immediately, since preinitialize() is only processed after the model starts to run.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

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

configure

public void configure(java.net.URL base,
                      java.lang.String source,
                      java.lang.String text)
               throws java.lang.Exception

Read the saved XML for this PtalonActor.

Specified by:

configure in interface Configurable

Parameters:

base - The base relative to which references within the input are found, or null if this is not known, or there is none.

source - The input source, which specifies a URL, or null if none.

text - Configuration information given as text, or null if none.

Throws:

java.lang.Exception - If something goes wrong.

getConfigureSource

public java.lang.String getConfigureSource()

Return the input source that was specified the last time the configure() method was called.

Specified by:

getConfigureSource in interface Configurable

Returns:

The string representation of the input URL, or null if the no source has been used to configure this object, or null if no external source need be used to configure this object.

getConfigureText

public java.lang.String getConfigureText()

Override the default behavior to always return null.

Specified by:

getConfigureText in interface Configurable

Returns:

null.

getMappedName

public java.lang.String getMappedName(java.lang.String ptalonName)
                               throws PtalonRuntimeException

Get the stored unique name for a symbol in the PtalonActor. The unique name comes from a call to uniqueName().

Parameters:

ptalonName - The symbol.

Returns:

The unique name.

Throws:

PtalonRuntimeException - If no such symbol exists.

getNestedDepth

public int getNestedDepth()

Return the depth of this PtalonActor declaration with respect to its creator. If this PtalonActor is not created by another PtalonActor's code, then the depth is zero. If, however, this PtalonActor is named Bar in some PtalonCode, and it is created with Foo(actorparameter0 := Bar()), then its depth will be 2, and the corresponding Foo container will have depth 1.

Returns:

The depth of this actor declaration with respect to its creator.

See Also:

setNestedDepth(int)

getPtalonParameter

public PtalonParameter getPtalonParameter(java.lang.String name)
                                   throws PtalonRuntimeException

Find the parameter in the Ptalon code with the specified name, and return the Ptolemy parameter (java) that was created.

Parameters:

name - The name of the parameter in the Ptalon code, which may be a prefix of the actual parameter's name.

Returns:

The PtalonParameter.

Throws:

PtalonRuntimeException - If no such PtalonParameter exists.

setNestedDepth

public void setNestedDepth(int depth)

Set the depth of this PtalonActor declaration with respect to its creator. If this PtalonActor is not created by another PtalonActor's code, then the depth will be zero. If, however, this PtalonActor is named Bar in some PtalonCode, and it is created with Foo(actorparameter0 := Bar()), then it's depth will be 2, and the corresponding Foo container will have depth 1.

Parameters:

depth - The of this actor declaration with respect to its creator.

See Also:

getNestedDepth()

uniqueName

public java.lang.String uniqueName(java.lang.String prefix)

Return a name that is guaranteed to not be the name of any contained attribute, port, class, entity, or relation. In this implementation, the argument is stripped of any numeric suffix, and then a numeric suffix is appended and incremented until a name is found that does not conflict with a contained attribute, port, class, entity, or relation. If this composite entity or any composite entity that it contains defers its MoML definition (i.e., it is an instance of a class or a subclass), then the prefix gets appended with "_n_", where n is the depth of this deferral. That is, if the object deferred to also defers, then n is incremented. This differs from the superclass in that a number is always appended in this class. This is mainly important for visualization of the created actors and their displayed names.

Overrides:

uniqueName in class CompositeEntity

Parameters:

prefix - A prefix for the name.

Returns:

A unique name.

_addAttribute

protected void _addAttribute(Attribute attribute)
                      throws NameDuplicationException,
                             IllegalActionException

Add the attribute, and if the attribute is a PtalonParameter, add it to a list of Ptalon parameters.

Overrides:

_addAttribute in class NamedObj

Parameters:

attribute - The attribute to be added.

Throws:

NameDuplicationException - If the superclass throws it.

IllegalActionException - If the superclass throws it.

_createPtalonEvaluator

protected PtalonEvaluator _createPtalonEvaluator(PtalonActor actor)

_createPtalonPopulator

protected PtalonPopulator _createPtalonPopulator()

_createPtalonRecognizer

protected PtalonRecognizer _createPtalonRecognizer(PtalonLexer lexer)

Create Ptalon parser. This function simply constructs a PtalonRecognizer instance with the given lexer. Subclasses may override this function to return a customized parser.

Parameters:

lexer - The lexer.

Returns:

The Ptalon parser.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object, which in this class is the configuration information. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character. Note that this only saves the values of the Ptalon parameters; it does not save other entities generated as a result of parsing the Ptalon file.

Overrides:

_exportMoMLContents in class CompositeEntity

Parameters:

output - The output stream for writing.

depth - The depth in the hierarchy, to determine indenting.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

NamedObj.exportMoML(Writer, int)

_initializePtalonActor

protected void _initializePtalonActor()

Initialize this PtalonActor. This method may be called when the PtalonActor is first constructed or if any of its parameter values are changed, so we only initialize variables that do not need to be saved when reparsing the Ptalon file.

_initializePtalonCodeLocation

protected void _initializePtalonCodeLocation()
                                      throws IllegalActionException

This helper method is used to begin the Ptalon compiler if the ptalonCodeLocation attribute has been updated.

Throws:

IllegalActionException - If any exception is thrown.

_removeContents

protected void _removeContents()

_isValueChanged

private boolean _isValueChanged(PtalonParameter p)
                         throws IllegalActionException

Return true if the value of the given PtalonParameter has changed. This method checks for newly assigned values (where the value was not previously asigned), changed expression values, and changed token values (as a result of a change to the value of the underlying expression).

Parameters:

p - The PtalonParameter to check.

Returns:

true If value has changed.

Throws:

IllegalActionException - If unable to compare the token value of p with its previously stored value.

See Also:

attributeChanged(Attribute)