
CompositeEntity |
ptolemy.kernel.CompositeEntity |
A CompositeEntity is a cluster in a clustered graph.
I.e., it is a non-atomic entity, in that
it can contain other entities and relations. It supports transparent ports,
where, in effect, the port of a contained entity is represented by a port
of this entity. Methods that "deeply" traverse the topology
see right through transparent ports.
It may be opaque, in which case its ports are opaque and methods
that "deeply" traverse the topology do not see through them.
For instance, deepEntityList() returns the opaque entities
directly or indirectly contained by this entity.
To add an entity or relation to this composite, call its
setContainer() method with this composite as an argument. To
remove it, call its setContainer() method with a null argument (or
another container). The entity must be an instance of
ComponentEntity and the relation of ComponentRelation or an
exception is thrown. Derived classes may further constrain these
to subclasses. To do that, they should override the protected
methods _addEntity() and _addRelation() and the public member
newRelation().
A CompositeEntity may be contained by another CompositeEntity.
To set that up, call the setContainer() method of the inside entity.
Derived classes may further constrain the container to be
a subclass of CompositeEntity. To do this, they should override
setContainer() to throw an exception. Recursive containment
structures, where an entity directly or indirectly contains itself,
are disallowed, and an exception is thrown on an attempt to set up
such a structure.
A CompositeEntity can contain instances of ComponentPort. By default
these ports will be transparent, although subclasses of CompositeEntity
can make them opaque by overriding the isOpaque() method to return
true. Derived classes may further constrain the ports to a
subclass of ComponentPort.
To do this, they should override the public method newPort() to create
a port of the appropriate subclass, and the protected method _addPort()
to throw an exception if its argument is a port that is not of the
appropriate subclass.
Since contained entities implement the
ptolemy.kernel.util.Instantiable interface,
some may be class definitions. If an entity is a class definition,
then it is not included in the lists returned by
entityList(), entityList(Class),
deepEntityList(), and allAtomicEntityList().
Correspondingly, if it is not a class definition, then it is not
included in the list returned by classDefinitionList().
Contained class definitions are nonetheless required to have names
distinct from contained entities that are not class definitions,
and the method getEntity(String) will return either
a class definition or an entity that is not a class definition,
as long as the name matches. Note that contained entities that
are class definitions cannot be connected to other entities.
Moreover, they cannot be deleted as long as there are either
subclasses or instances present.
Author(s): John S. Davis II, Edward A. Lee
Version:$Id: CompositeEntity.java,v 1.164 2006/03/30 16:35:45 cxh Exp $
Pt.Proposed Rating:Green (eal)
Pt.Accepted Rating:Green (hyzheng)