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 {@link 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 {@link #entityList()}, {@link #entityList(Class)}, {@link #deepEntityList()}, and {@link #allAtomicEntityList()}. Correspondingly, if it is not a class definition, then it is not included in the list returned by {@link #classDefinitionList()}. Contained class definitions are nonetheless required to have names distinct from contained entities that are not class definitions, and the method {@link #getEntity(String)} will return eithera 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 John S. Davis II, Edward A. Lee, contributor: Christopher Brooks
@version $Id: CompositeEntity.java,v 1.185 2007/12/07 06:24:42 cxh Exp $
@since Ptolemy II 0.2
@Pt.ProposedRating Green (eal)
@Pt.AcceptedRating Green (hyzheng)