ptolemy.actor
Class CompositeActor

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

All Implemented Interfaces:

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

Direct Known Subclasses:

Configurer, Configurer, TypedCompositeActor, TypeOpaqueCompositeActor

public class CompositeActor
extends CompositeEntity
implements Actor, FiringsRecordable

A CompositeActor is an aggregation of actors. It may have a local director, which is an attribute of class Director that is responsible for executing the contained actors. At the top level of a hierarchy, a composite actor (the toplevel CompositeActor of the topology) will normally exist with a local Director, and no container. A composite actor at a lower level of the hierarchy may also have a local director. A composite actor with a local director is opaque, and serves the role of the wormhole from Ptolemy Classic. Its ports are opaque, but it can contain actors and relations. The toplevel composite actor is also associated with a Manager object that is responsible for managing any execution within the topology at a high level.

The executive director of a composite actor is the local director of the actor's container. The toplevel composite actor has no executive director, and getExecutiveDirector will return null. For transparent composite actors, the executive director and the local director will be the same.

The getDirector() method returns the local director if there is one. Otherwise, it returns the executive director of the CompositeActor, if there is one. Whatever it returns is called (simply) the director of the composite (it may be local or executive). This Director is responsible for the execution of all the actors contained within the composite actor.

A composite actor must have an executive director in order to communicate with the hierarchy around it. In fact, it cannot even receive data in its input ports without an executive director, since the executive director is responsible for supplying the receivers to the ports. The toplevel composite actor has no executive director and cannot have ports that transmit data, but it can still be executed as long as it has a local director. If the getDirector() method returns null, then the composite is not executable.

When a composite actor has both a director and an executive director, then the model of computation implemented by the director need not be the same as the model of computation implemented by the executive director. This is the source of the hierarchical heterogeneity in Ptolemy II. Multiple models of computation can be cleanly nested.

The ports of a CompositeActor are constrained to be IOPorts, the relations to be IORelations, and the actors to be instances of ComponentEntity that implement the Actor interface. Derived classes may impose further constraints by overriding newPort(), _addPort(), newRelation(), _addRelation(), and _addEntity().

Since:

Ptolemy II 0.2

Version:

$Id: CompositeActor.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer, Contributor: Daniel Crawl, Bert Rodiers

See Also:

IOPort, IORelation, ComponentEntity, Director, Manager, Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Green (cxh)

Nested Class Summary

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

CompositeEntity.ContainedObjectsIterator

Field Summary

protected java.util.LinkedList<ActorFiringListener>	_actorFiringListeners The list of ActorFiringListeners registered with this object.
private java.util.List<IOPort>	_cachedInputPorts
private java.util.List<IOPort>	_cachedOutputPorts
protected CausalityInterface	_causalityInterface The causality interface, if it has been created.
private Director	_causalityInterfaceDirector The director for which the causality interface was created.
private java.util.Set<Executable>	_derivedPiggybacks The derived piggybacked executables.
private Director	_director
private boolean	_inConnectionsChanged
protected java.util.List<Initializable>	_initializables List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
private long	_inputPortsVersion
private Manager	_manager
protected boolean	_notifyingActorFiring Flag that is true if there are actor firing listeners.
private long	_outputPortsVersion
private java.util.List<Executable>	_piggybacks List piggybacked objects.
protected java.util.Map<java.lang.String,java.util.List<IOPort>>	_publishedPorts Keep track of all published ports accessable in this container.
protected java.util.Map<java.lang.String,IORelation>	_publisherRelations Keep track of all relations with published ports accessable in this container.
private long	_receiversVersion Record of the workspace version the last time receivers were created.
private RelationWidthInference	_relationWidthInference
protected boolean	_stopRequested Indicator that a stop has been requested by a call to stop().

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

CompositeActor()
Construct a CompositeActor in the default workspace with no container and an empty string as its name.

CompositeActor(CompositeEntity container, java.lang.String name)
Create an actor with a name and a container.

CompositeActor(Workspace workspace)
Construct a CompositeActor in the specified workspace with no container and an empty string as a name.

Method Summary

protected void	_actorFiring(FiringEvent.FiringEventType type, int multiplicity) Send an actor firing event type to all actor firing listeners that have registered with this actor.
protected void	_actorFiring(FiringEvent event) Send an actor firing event to all actor firing listeners that have registered with this actor.
protected void	_addEntity(ComponentEntity entity) Add an actor to this container with minimal error checking.
protected void	_addPort(Port port) Add a port to this actor.
protected void	_addRelation(ComponentRelation relation) Add a relation to this container.
protected void	_finishedAddEntity(ComponentEntity entity) Notify this actor that the given entity has been added inside it.
protected IOPort	_getPublishedPort(java.lang.String name) Get the published port with name name.
private void	_getTransparentActorPiggybacks(java.util.Set<Executable> piggybacks, boolean addPiggyBackAtThisLevel) Fill in the piggybacks in the containted transparent CompositeActors.
private RelationWidthInference	_getWidthInferenceAlgorithm() Return the RelationWidthInference algorithm.
protected void	_setDirector(Director director) Set the local director for execution of this CompositeActor.
void	addActorFiringListener(ActorFiringListener listener) Append a listener to the current set of actor firing listeners.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	addPiggyback(Executable piggyback) Add the specified object to the list of objects whose action methods should be invoked upon invocation of the corresponding actions methods of this object.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	connectionsChanged(Port port) Invalidate the schedule and type resolution and create new receivers if the specified port is an opaque output port.
void	createReceivers() Create receivers for each port.
void	createSchedule() Create the schedule for this model, if necessary.
void	fire() If this actor is opaque, transfer any data from the input ports of this composite to the ports connected on the inside, and then invoke the fire() method of its local director.
CausalityInterface	getCausalityInterface() Return a causality interface for this actor.
Director	getDirector() Return the director responsible for execution of the contained actors.
Director	getExecutiveDirector() Return the executive director of this CompositeActor.
Manager	getManager() Get the manager responsible for execution of this composite actor.
boolean	inferringWidths() Determine whether widths are currently being inferred or not.
void	inferWidths() Infer the width of the relations for which no width has been specified yet.
void	initialize() Initialize this actor.
java.util.List	inputPortList() List the input ports of this actor.
boolean	isFireFunctional() If this actor is opaque, invoke the isFireFunctional() method of the local director and return its result.
boolean	isOpaque() Return true if this actor contains a local director.
boolean	isStrict() If this actor is opaque, invoke the isStrict() method of the local director and return its result.
int	iterate(int count) Invoke a specified number of iterations of the actor.
void	linkToPublishedPort(java.util.regex.Pattern pattern, TypedIOPort subscriberPort) Link the subscriberPort with a already registered "published port" coming from a publisher.
void	linkToPublishedPort(java.lang.String name, IOPort subscriberPort) Link the subscriberPort with a already registered "published port" coming from a publisher.
boolean	needsWidthInference() Return whether the current widths of the relation in the model are no longer valid anymore and the widths need to be inferred again.
Receiver	newInsideReceiver() Return a new receiver of a type compatible with the local director.
Port	newPort(java.lang.String name) Create a new IOPort with the specified name.
Receiver	newReceiver() Return a new receiver of a type compatible with the executive director.
ComponentRelation	newRelation(java.lang.String name) Create a new IORelation with the specified name, add it to the relation list, and return it.
void	notifyConnectivityChange() Notify the manager that the connectivity in the model changed (width of relation changed, relations added, linked to different ports, ...).
java.util.List	outputPortList() Return an enumeration of the output ports.
boolean	postfire() If this actor is opaque, invoke the postfire() method of its local director and transfer output data.
boolean	prefire() If this actor is opaque, invoke the prefire() method of the local director.
void	preinitialize() Create receivers and invoke the preinitialize() method of the local director.
void	recordFiring(FiringEvent.FiringEventType type) Record a firing event.
void	registerPublisherPort(java.lang.String name, IOPort port) Register a "published port" coming from a publisher.
void	removeActorFiringListener(ActorFiringListener listener) Unregister an actor firing listener.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), intialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	removePiggyback(Executable piggyback) Remove the specified object from the list of objects whose action methods should be invoked upon invocation of the corresponding actions methods of this object.
void	requestChange(ChangeRequest change) Queue a change request.
void	setContainer(CompositeEntity container) Override the base class to invalidate the schedule and resolved types of the director.
void	setDirector(Director director) Set the local director for execution of this CompositeActor.
void	setManager(Manager manager) Set the Manager for execution of this CompositeActor.
void	stop() Request that execution stop as soon as possible.
void	stopFire() Request that execution of the current iteration complete.
void	terminate() If this is an opaque CompositeActor, then look to our director for help.
void	unlinkToPublishedPort(java.util.regex.Pattern pattern, TypedIOPort subscriberPort) Unlink the subscriberPort with a already registered "published port" coming from a publisher.
void	unlinkToPublishedPort(java.lang.String name, IOPort subscriberPort) Unlink the subscriberPort with a already registered "published port" coming from a publisher.
void	unregisterPublisherPort(java.lang.String name, IOPort publisherPort) Unregister a "published port" coming from a publisher.
void	wrapup() If this actor is opaque, then invoke the wrapup() method of the local director.

Methods inherited from class ptolemy.kernel.CompositeEntity

_adjustDeferrals, _deepOpaqueEntityList, _description, _exportMoMLContents, _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, uniqueName

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

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, 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.kernel.util.Nameable

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

_actorFiringListeners

protected java.util.LinkedList<ActorFiringListener> _actorFiringListeners

The list of ActorFiringListeners registered with this object. NOTE: Because of the way we synchronize on this object, it should never be reset to null after the first list is created.

_causalityInterface

protected CausalityInterface _causalityInterface

The causality interface, if it has been created.

_initializables

protected transient java.util.List<Initializable> _initializables

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

_notifyingActorFiring

protected boolean _notifyingActorFiring

Flag that is true if there are actor firing listeners.

_publishedPorts

protected java.util.Map<java.lang.String,java.util.List<IOPort>> _publishedPorts

Keep track of all published ports accessable in this container.

_publisherRelations

protected java.util.Map<java.lang.String,IORelation> _publisherRelations

Keep track of all relations with published ports accessable in this container.

_stopRequested

protected boolean _stopRequested

Indicator that a stop has been requested by a call to stop().

_derivedPiggybacks

private transient java.util.Set<Executable> _derivedPiggybacks

The derived piggybacked executables. Derived piggybacked executables are executables that are added to transparent composite actors that are contained by this composite actor. These should also piggy back on this actor. These are only filled in if this actor is a opaque composite actor.

_director

private Director _director

_inConnectionsChanged

private boolean _inConnectionsChanged

_manager

private Manager _manager

_inputPortsVersion

private transient long _inputPortsVersion

_cachedInputPorts

private transient java.util.List<IOPort> _cachedInputPorts

_outputPortsVersion

private transient long _outputPortsVersion

_cachedOutputPorts

private transient java.util.List<IOPort> _cachedOutputPorts

_causalityInterfaceDirector

private Director _causalityInterfaceDirector

The director for which the causality interface was created.

_piggybacks

private transient java.util.List<Executable> _piggybacks

List piggybacked objects.

_receiversVersion

private long _receiversVersion

Record of the workspace version the last time receivers were created.

_relationWidthInference

private RelationWidthInference _relationWidthInference

Constructor Detail

CompositeActor

public CompositeActor()

Construct a CompositeActor in the default workspace with no container and an empty string as its name. Add the actor to the workspace directory. You should set a director before attempting to execute it. You should set the container before sending data to it. Increment the version number of the workspace.

CompositeActor

public CompositeActor(Workspace workspace)

Construct a CompositeActor in the specified workspace with no container and an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. You should set a director before attempting to execute it. You should set the container before sending data to it. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the actor.

CompositeActor

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

Create an actor 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. You should set a director before attempting to execute it.

Parameters:

container - The container actor.

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

addActorFiringListener

public void addActorFiringListener(ActorFiringListener listener)

Append a listener to the current set of actor firing listeners. If the listener is already in the set, it will not be added again. Note that this method is basically the same as addDebugListener in the class NamedObj.

Specified by:

addActorFiringListener in interface FiringsRecordable

Parameters:

listener - The listener to which to send actor firing messages.

See Also:

removeActorFiringListener(ActorFiringListener)

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), intialize(), 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), addPiggyback(Executable)

addPiggyback

public void addPiggyback(Executable piggyback)

Add the specified object to the list of objects whose action methods should be invoked upon invocation of the corresponding actions methods of this object.

Parameters:

piggyback - The piggyback object.

See Also:

addInitializable(Initializable), removePiggyback(Executable)

clone

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

Clone the actor into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a composite actor with clones of the ports of the original actor, the contained actors, and the contained relations. The ports of the returned actor are not connected to anything. The connections of the relations are duplicated in the new composite, unless they cross levels, in which case an exception is thrown. The local director is cloned, if there is one. The executive director is not cloned. NOTE: This will not work if there are level-crossing transitions.

Overrides:

clone in class CompositeEntity

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new CompositeActor.

Throws:

java.lang.CloneNotSupportedException - If the actor contains level crossing transitions so that its connections cannot be cloned, or if one of the attributes cannot be cloned.

See Also:

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

connectionsChanged

public void connectionsChanged(Port port)

Invalidate the schedule and type resolution and create new receivers if the specified port is an opaque output port. Also, notify the containers of any ports deeply connected on the inside by calling their connectionsChanged() methods, since their width may have changed.

Overrides:

connectionsChanged in class Entity

Parameters:

port - The port that has connection changes.

fire

public void fire()
          throws IllegalActionException

If this actor is opaque, transfer any data from the input ports of this composite to the ports connected on the inside, and then invoke the fire() method of its local director. The transfer is accomplished by calling the transferInputs() method of the local director (the exact behavior of which depends on the domain). If the actor is not opaque, throw an exception. This method is read-synchronized on the workspace, so the fire() method of the director need not be (assuming it is only called from here). After the fire() method of the director returns, send any output data created by calling the local director's transferOutputs method.

Specified by:

fire in interface Executable

Throws:

IllegalActionException - If there is no director, or if the director's fire() method throws it, or if the actor is not opaque.

createReceivers

public void createReceivers()
                     throws IllegalActionException

Create receivers for each port. If the port is an input port, then receivers are created for outside connections. If it is an output port, then receivers are created for inside connections. This method replaces any pre-existing receivers, so any data they contain will be lost.

Specified by:

createReceivers in interface Actor

Throws:

IllegalActionException - If any port throws it.

See Also:

AtomicActor.createReceivers(), createReceivers()

createSchedule

public void createSchedule()
                    throws IllegalActionException

Create the schedule for this model, if necessary.

Throws:

IllegalActionException - If the schedule can't be created.

getCausalityInterface

public CausalityInterface getCausalityInterface()

Return a causality interface for this actor. This returns an instance of CausalityInterfaceForComposites. If this is called multiple times, the same object is returned each time unless the director has changed since the last call, in which case a new object is returned.

Specified by:

getCausalityInterface in interface Actor

Returns:

A representation of the dependencies between input ports and output ports.

getDirector

public Director getDirector()

Return the director responsible for execution of the contained actors. This will be either the local director (if it exists) or the executive director (obtained using getExecutiveDirector()). This method is read-synchronized on the workspace.

Specified by:

getDirector in interface Actor

Returns:

The director responsible for invocation of inside actors.

See Also:

setDirector(Director)

getExecutiveDirector

public Director getExecutiveDirector()

Return the executive director of this CompositeActor. The container (if any) is queried for its (local) director. If it has none, or there is no container, then return null. This method is read-synchronized on the workspace.

Specified by:

getExecutiveDirector in interface Actor

Returns:

The executive director of this composite actor.

getManager

public Manager getManager()

Get the manager responsible for execution of this composite actor. If this is the toplevel composite actor, then return what was set with setManager(). For others, recursively call on the container, until the toplevel composite actor is reached. This method is read-synchronized on the workspace.

Specified by:

getManager in interface Actor

Returns:

The Manager of the topology that contains the composite actor.

See Also:

setManager(Manager)

inferringWidths

public boolean inferringWidths()

Determine whether widths are currently being inferred or not.

Returns:

True When widths are currently being inferred.

inferWidths

public void inferWidths()
                 throws IllegalActionException

Infer the width of the relations for which no width has been specified yet. The specified actor must be the top level container of the model.

Throws:

IllegalActionException - If the widths of the relations at port are not consistent or if the width cannot be inferred for a relation.

initialize

public void initialize()
                throws IllegalActionException

Initialize this actor. If this actor is opaque, invoke the initialize() method of its local director. Otherwise, throw an exception. This method is read-synchronized on the workspace, so the initialize() method of the director need not be (assuming it is only called from here).

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If there is no director, or if the director's initialize() method throws it, or if the actor is not opaque.

inputPortList

public java.util.List inputPortList()

List the input ports of this actor. Note that this method returns the ports directly contained by this actor, whether they are transparent or not. This method is read-synchronized on the workspace.

Specified by:

inputPortList in interface Actor

Returns:

A list of IOPort objects.

isFireFunctional

public boolean isFireFunctional()

If this actor is opaque, invoke the isFireFunctional() method of the local director and return its result. Otherwise, return true. Normally this method will not be invoked on a non-opaque composite actor.

Specified by:

isFireFunctional in interface Executable

Returns:

True if the local director's isFireFunctional() method returns true or if this actor is not opaque.

isOpaque

public boolean isOpaque()

Return true if this actor contains a local director. Otherwise, return false. This method is not synchronized on the workspace, so the caller should be.

Overrides:

isOpaque in class CompositeEntity

Returns:

True if the entity is opaque.

See Also:

CompositeEntity

isStrict

public boolean isStrict()
                 throws IllegalActionException

If this actor is opaque, invoke the isStrict() method of the local director and return its result. Otherwise, return true. Normally this method will not be invoked on a non-opaque composite actor.

Specified by:

isStrict in interface Executable

Returns:

True if the local director's isStrict() method returns true or if this actor is not opaque.

Throws:

IllegalActionException - Thrown if causality interface cannot be computed.

iterate

public int iterate(int count)
            throws IllegalActionException

Invoke a specified number of iterations of the actor. An iteration is equivalent to invoking prefire(), fire(), and postfire(), in that order. In an iteration, if prefire() returns true, then fire() will be called once, followed by postfire(). Otherwise, if prefire() returns false, fire() and postfire() are not invoked, and this method returns NOT_READY. If postfire() returns false, then no more iterations are invoked, and this method returns STOP_ITERATING. Otherwise, it returns COMPLETED. If stop() is called during this iteration, then cease iterating and return STOP_ITERATING.

This base class method actually invokes prefire(), fire(), and postfire(), as described above, but a derived class may override the method to execute more efficient code.

Specified by:

iterate in interface Executable

Parameters:

count - The number of iterations to perform.

Returns:

NOT_READY, STOP_ITERATING, or COMPLETED.

Throws:

IllegalActionException - If iterating is not permitted, or if prefire(), fire(), or postfire() throw it.

linkToPublishedPort

public void linkToPublishedPort(java.lang.String name,
                                IOPort subscriberPort)
                         throws IllegalActionException,
                                NameDuplicationException

Link the subscriberPort with a already registered "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

name - The name is being used in the matching process to match publisher and subscriber.

subscriberPort - The subscribed port.

Throws:

NameDuplicationException - If there are name conflicts as a result of the added relations or ports.

IllegalActionException - If the published port cannot be found.

linkToPublishedPort

public void linkToPublishedPort(java.util.regex.Pattern pattern,
                                TypedIOPort subscriberPort)
                         throws IllegalActionException,
                                NameDuplicationException

Link the subscriberPort with a already registered "published port" coming from a publisher. The pattern represents the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

pattern - The pattern is being used in the matching process to match publisher and subscriber.

subscriberPort - The subscribed port.

Throws:

NameDuplicationException - If there are name conflicts as a result of the added relations or ports.

IllegalActionException - If the published port cannot be found.

needsWidthInference

public boolean needsWidthInference()
                            throws KernelRuntimeException

Return whether the current widths of the relation in the model are no longer valid anymore and the widths need to be inferred again.

Returns:

True when width inference needs to be executed again.

Throws:

KernelRuntimeException - If toplevel not a CompositeActor.

notifyConnectivityChange

public void notifyConnectivityChange()

Notify the manager that the connectivity in the model changed (width of relation changed, relations added, linked to different ports, ...). This will invalidate the current width inference.

newInsideReceiver

public Receiver newInsideReceiver()
                           throws IllegalActionException

Return a new receiver of a type compatible with the local director. Derived classes may further specialize this to return a receiver specialized to the particular actor. This method is not synchronized on the workspace, so the caller should be.

Returns:

A new object implementing the Receiver interface.

Throws:

IllegalActionException - If there is no local director.

newPort

public Port newPort(java.lang.String name)
             throws NameDuplicationException

Create a new IOPort with the specified name. The container of the port is set to this actor. This method is write-synchronized on the workspace.

Overrides:

newPort in class ComponentEntity

Parameters:

name - The name for the new port.

Returns:

The new port.

Throws:

NameDuplicationException - If the actor already has a port with the specified name.

newReceiver

public Receiver newReceiver()
                     throws IllegalActionException

Return a new receiver of a type compatible with the executive director. Derived classes may further specialize this to return a receiver specialized to the particular actor. This method is not synchronized on the workspace, so the caller should be.

Specified by:

newReceiver in interface Actor

Returns:

A new object implementing the Receiver interface.

Throws:

IllegalActionException - If there is no executive director.

newRelation

public ComponentRelation newRelation(java.lang.String name)
                              throws IllegalActionException,
                                     NameDuplicationException

Create a new IORelation with the specified name, add it to the relation list, and return it. Derived classes can override this to create domain-specific subclasses of IORelation. This method is write-synchronized on the workspace.

Overrides:

newRelation in class CompositeEntity

Parameters:

name - The name of the new relation.

Returns:

The new relation.

Throws:

IllegalActionException - If name argument is null.

NameDuplicationException - If name collides with a name already on the container's contents list.

outputPortList

public java.util.List outputPortList()

Return an enumeration of the output ports. Note that this method returns the ports directly contained by this actor, whether they are transparent or not. This method is read-synchronized on the workspace.

Specified by:

outputPortList in interface Actor

Returns:

An enumeration of IOPort objects.

postfire

public boolean postfire()
                 throws IllegalActionException

If this actor is opaque, invoke the postfire() method of its local director and transfer output data. Specifically, transfer any data from the output ports of this composite to the ports connected on the outside. The transfer is accomplished by calling the transferOutputs() method of the executive director. If there is no executive director, then no transfer occurs. This method is read-synchronized on the workspace.

Specified by:

postfire in interface Executable

Returns:

True if the execution can continue into the next iteration.

Throws:

IllegalActionException - If there is no director, or if the director's postfire() method throws it, or if this actor is not opaque.

prefire

public boolean prefire()
                throws IllegalActionException

If this actor is opaque, invoke the prefire() method of the local director. This method returns true if the actor is ready to fire (determined by the prefire() method of the director). It is read-synchronized on the workspace.

Specified by:

prefire in interface Executable

Returns:

True if the iteration can proceed.

Throws:

IllegalActionException - If there is no director, or if the director's prefire() method throws it, or if this actor is not opaque.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Create receivers and invoke the preinitialize() method of the local director. If this actor is not opaque, throw an exception. This method also resets the protected variable _stopRequested to false, so if a derived class overrides this method, then it should also do that. This method is read-synchronized on the workspace, so the preinitialize() method of the director need not be, assuming it is only called from here.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If there is no director, or if the director's preinitialize() method throws it, or if this actor is not opaque.

recordFiring

public void recordFiring(FiringEvent.FiringEventType type)

Record a firing event.

Specified by:

recordFiring in interface FiringsRecordable

Parameters:

type - The firing event to be recorded.

registerPublisherPort

public void registerPublisherPort(java.lang.String name,
                                  IOPort port)
                           throws NameDuplicationException,
                                  IllegalActionException

Register a "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the same name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

name - The name is being used in the matching process to match publisher and subscriber.

port - The published port.

Throws:

NameDuplicationException - If the published port is already registered.

IllegalActionException - If the published port can't be added.

removeActorFiringListener

public void removeActorFiringListener(ActorFiringListener listener)

Unregister an actor firing listener. If the specified listener has not been previously registered, then do nothing. Note that this method is basically the same as removeDebugListener in the class NamedObj.

Specified by:

removeActorFiringListener in interface FiringsRecordable

Parameters:

listener - The listener to remove from the list of listeners to which actor firing messages are sent.

See Also:

addActorFiringListener(ActorFiringListener)

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), intialize(), 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), removePiggyback(Executable)

removePiggyback

public void removePiggyback(Executable piggyback)

Remove the specified object from the list of objects whose action methods should be invoked upon invocation of the corresponding actions methods of this object. If the specified object is not on the list, do nothing.

Parameters:

piggyback - The piggyback object.

See Also:

removeInitializable(Initializable), addPiggyback(Executable)

requestChange

public void requestChange(ChangeRequest change)

Queue a change request. If there is a manager, then first call stopFire() before deferring to the base class.

Specified by:

requestChange in interface Changeable

Overrides:

requestChange in class NamedObj

Parameters:

change - The requested change.

See Also:

NamedObj.executeChangeRequests(), NamedObj.setDeferringChangeRequests(boolean), Changeable

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to invalidate the schedule and resolved types of the director.

Overrides:

setContainer in class CompositeEntity

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:

ComponentEntity.getContainer()

setDirector

public void setDirector(Director director)
                 throws IllegalActionException,
                        NameDuplicationException

Set the local director for execution of this CompositeActor. Calling this method with a non-null argument makes this entity opaque. Calling it with a null argument makes it transparent. The container of the specified director is set to this composite actor, and if there was previously a local director, its container is set to null. This method is write-synchronized on the workspace. NOTE: Calling this method is almost equivalent to calling setContainer() on the director with this composite as an argument. The difference is that if you call this method with a null argument, it effectively removes the director from its role as director, but without removing it from its container.

Parameters:

director - The Director responsible for execution.

Throws:

IllegalActionException - If the director is not in the same workspace as this actor. It may also be thrown in derived classes if the director is not compatible.

NameDuplicationException - If an attribute already exists in this container with the same name as the given director.

See Also:

getDirector()

setManager

public void setManager(Manager manager)
                throws IllegalActionException

Set the Manager for execution of this CompositeActor. This can only be done for a composite actor that has no container. For others, the Manager is inherited from the container. This method is write-synchronized on the workspace.

Parameters:

manager - The Manager

Throws:

IllegalActionException - If this actor has a container, or the manager is not in the same workspace as this actor.

See Also:

getManager()

stop

public void stop()

Request that execution stop as soon as possible. This sets a flag indicating that this request has been made (the protected variable _stopRequested). If this actor is opaque, then invoke the stop() method of the local director. This method is read-synchronized on the workspace.

Specified by:

stop in interface Executable

stopFire

public void stopFire()

Request that execution of the current iteration complete. If this actor is opaque, then invoke the stopFire() method of the local director, if there is one. Otherwise, do nothing. This method is read-synchronized on the workspace.

Specified by:

stopFire in interface Executable

terminate

public void terminate()

If this is an opaque CompositeActor, then look to our director for help. If we are transparent, then we really shouldn't have been called, so just ignore.

Specified by:

terminate in interface Executable

unlinkToPublishedPort

public void unlinkToPublishedPort(java.lang.String name,
                                  IOPort subscriberPort)
                           throws IllegalActionException

Unlink the subscriberPort with a already registered "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

name - The name is being used in the matching process to match publisher and subscriber.

subscriberPort - The subscribed port.

Throws:

NameDuplicationException - If there are name conflicts as a result of the added relations or ports.

IllegalActionException - If the published port cannot be found.

unlinkToPublishedPort

public void unlinkToPublishedPort(java.util.regex.Pattern pattern,
                                  TypedIOPort subscriberPort)
                           throws IllegalActionException

Unlink the subscriberPort with a already registered "published port" coming from a publisher. The pattern is the pattern being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

pattern - The pattern is being used in the matching process to match publisher and subscriber.

subscriberPort - The subscribed port.

Throws:

NameDuplicationException - If there are name conflicts as a result of the added relations or ports.

IllegalActionException - If the published port cannot be found.

unregisterPublisherPort

public void unregisterPublisherPort(java.lang.String name,
                                    IOPort publisherPort)

Unregister a "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the same name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.

Parameters:

name - The name is being used in the matching process to match publisher and subscriber. This will be the port that should be removed

publisherPort - The publisher port.

wrapup

public void wrapup()
            throws IllegalActionException

If this actor is opaque, then invoke the wrapup() method of the local director. This method is read-synchronized on the workspace.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - If there is no director, or if the director's wrapup() method throws it, or if this actor is not opaque.

_actorFiring

protected final void _actorFiring(FiringEvent event)

Send an actor firing event to all actor firing listeners that have registered with this actor.

Parameters:

event - The event.

_actorFiring

protected final void _actorFiring(FiringEvent.FiringEventType type,
                                  int multiplicity)

Send an actor firing event type to all actor firing listeners that have registered with this actor.

Parameters:

type - The type.

multiplicity - The multiplicity of the firing, that is, the number of times the firing will occur or has occurred.

_addEntity

protected void _addEntity(ComponentEntity entity)
                   throws IllegalActionException,
                          NameDuplicationException

Add an actor to this container with minimal error checking. This overrides the base-class method to make sure the argument implements the Actor interface. It is not synchronized on the workspace, so the caller should be.

Overrides:

_addEntity in class CompositeEntity

Parameters:

entity - Actor to contain.

Throws:

IllegalActionException - If the actor has no name, or the action would result in a recursive containment structure, or the argument does not implement the Actor interface.

NameDuplicationException - If the name collides with a name already on the actor contents list.

_addPort

protected void _addPort(Port port)
                 throws IllegalActionException,
                        NameDuplicationException

Add a port to this actor. This overrides the base class to throw an exception if the added port is not an instance of IOPort. This method should not be used directly. Call the setContainer() method of the port instead. This method does not set the container of the port to point to this actor. It assumes that the port is in the same workspace as this actor, but does not check. The caller should check. This method is not synchronized on the workspace, so the caller should be.

Overrides:

_addPort in class ComponentEntity

Parameters:

port - The port to add to this actor.

Throws:

IllegalActionException - If the port class is not acceptable to this actor, or the port has no name.

NameDuplicationException - If the port name collides with a name already in the actor.

_addRelation

protected void _addRelation(ComponentRelation relation)
                     throws IllegalActionException,
                            NameDuplicationException

Add a relation to this container. This method should not be used directly. Call the setContainer() method of the relation instead. This method does not set the container of the relation to refer to this container. This method is not synchronized on the workspace, so the caller should be.

Overrides:

_addRelation in class CompositeEntity

Parameters:

relation - Relation to contain.

Throws:

IllegalActionException - If the relation has no name, or is not an instance of IORelation.

NameDuplicationException - If the name collides with a name already on the contained relations list.

_finishedAddEntity

protected void _finishedAddEntity(ComponentEntity entity)

Notify this actor that the given entity has been added inside it. This overrides the base-class method to invalidate the schedule and type resolution, and to request initialization with the director. This method does not alter the actor in any way. It is not synchronized on the workspace, so the caller should be.

Overrides:

_finishedAddEntity in class CompositeEntity

Parameters:

entity - Actor to contain.

Throws:

IllegalActionException - If the actor has no name, or the action would result in a recursive containment structure, or the argument does not implement the Actor interface.

NameDuplicationException - If the name collides with a name already on the actor contents list.

_getPublishedPort

protected final IOPort _getPublishedPort(java.lang.String name)
                                  throws IllegalActionException,
                                         NameDuplicationException

Get the published port with name name.

Parameters:

name - The name of the published port.

Returns:

The port of the publisher that has name nname.

Throws:

IllegalActionException - If the publisher can't be found.

NameDuplicationException - If there are multiple publishers with the same name.

_setDirector

protected void _setDirector(Director director)
                     throws IllegalActionException,
                            NameDuplicationException

Set the local director for execution of this CompositeActor. This should not be called be directly. Instead, call setContainer() on the director. This method removes any previous director from this container, and caches a local reference to the director so that this composite does not need to search its attributes each time the director is accessed.

Parameters:

director - The Director responsible for execution.

Throws:

IllegalActionException - If removing the old director causes this to be thrown. Should not be thrown.

NameDuplicationException - If removing the old director causes this to be thrown. Should not be thrown.

_getTransparentActorPiggybacks

private void _getTransparentActorPiggybacks(java.util.Set<Executable> piggybacks,
                                            boolean addPiggyBackAtThisLevel)

Fill in the piggybacks in the containted transparent CompositeActors. If addPiggyBackAtThisLevel equals to True, the piggybacks directly in this composite actor will also be included.

Parameters:

piggybacks - The piggybacks that will be filled it.

addPiggyBackAtThisLevel - True when the piggybacks directly in this composite actor should also be included.

_getWidthInferenceAlgorithm

private RelationWidthInference _getWidthInferenceAlgorithm()

Return the RelationWidthInference algorithm. _relationWidthInference is only stored at the top CompositeActor for the complete model.

Returns:

The RelationWidthInference algorithm.

Throws:

KernelRuntimeException - If toplevel not a CompositeActor.