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

_causalityInterface

_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.

_publisherRelations

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

_stopRequested

protected boolean _stopRequested

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

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

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

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.

Method Detail

addActorFiringListener

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.

addPiggyback

Add the specified object to the set of objects whose action
methods should be invoked upon invocation of the corresponding
actions methods of this object. These methods will be invoked
before the corresponding methods of this object.

clone

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.

connectionsChanged

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.

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

createReceivers

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.

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.

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.

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.

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.

initialize

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

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.

isStrict

Return false if all input ports have non-empty default values,
or if this actor is opaque and the contained director indicates
that it is non-strict.
Normally this method will not be invoked on a non-opaque
composite actor.
Note that ParameterPort is not treated as having a default value
because such ports might be used in a context where it is important
to supply them with an input value.

iterate

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.

linkToPublishedPort

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.

linkToPublishedPort

Link the subscriberPort with an already registered "published port" coming
from a publisher. The name gives the channel that
matches the publisher and subscriber.
The publisher is registered before the model is preinitialized,
when its channel parameter is set.
The subscribers call this method
to look for publishers during the preinitialization phase.

Parameters:

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

subscriberPort - The subscriber port.

global - Specification of whether the data is subscribed
globally. If set to true, then subscribers will see values
published by publishers anywhere in the model that reference
the same channel by name. If set to false, then only values
published by publishers that are fired by the same director
are seen by this subscriber.

linkToPublishedPort

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.

linkToPublishedPort

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.

global - Specification of whether the data is subscribed
globally. If set to true, then subscribers will see values
published by publishers anywhere in the model that reference
the same channel by name. If set to false, then only values
published by publishers that are fired by the same director
are seen by this subscriber.

newInsideReceiver

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.

newReceiver

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.

newRelation

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.

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.

postfire

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.

prefire

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.

preinitialize

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.

registerPublisherPort

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.

registerPublisherPort

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.
This call is ignored if this composite is a class definition
or is within a class definition.

Parameters:

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

port - The published port.

global - If true, publish globally. If false, publish
only to subscribers that are fired by the same director.

removeActorFiringListener

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.

removeInitializable

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

removePiggyback

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.

setDirector

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.

setManager

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.

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.

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.

unlinkToPublishedPort

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.

unlinkToPublishedPort

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.

global - Specification of whether the data is subscribed
globally. If set to true, then subscribers will see values
published by publishers anywhere in the model that reference
the same channel by name. If set to false, then only values
published by publishers that are fired by the same director
are seen by this subscriber.

unlinkToPublishedPort

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.

unlinkToPublishedPort

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.

global - Specification of whether the data is subscribed
globally. If set to true, then subscribers will see values
published by publishers anywhere in the model that reference
the same channel by name. If set to false, then only values
published by publishers that are fired by the same director
are seen by this subscriber.

unregisterPublisherPort

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

unregisterPublisherPort

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

_addEntity

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.

_addPort

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.

_addRelation

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.

_finishedAddEntity

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.

_setDirector

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.