Class ComponentEntity<T extends ComponentPort>

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    AtomicActor, AtomicComponent, CompositeEntity, Concept, State, SyntacticNode

    public class ComponentEntity<T extends ComponentPort>
    extends Entity<T>
    A ComponentEntity is a component in a CompositeEntity. It might itself be composite, but in this base class it is assumed to be atomic (meaning that it cannot contain components).

    Derived classes may further constrain the container to be a subclass of CompositeEntity. To do this, they should override the protected method _checkContainer() to throw an exception.

    A ComponentEntity can contain instances of ComponentPort. Derived classes may further constrain 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:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    John S. Davis II, Edward A. Lee
    Pt.AcceptedRating:
    Green (cxh)
    Pt.ProposedRating:
    Green (eal)
    • Constructor Detail

      • ComponentEntity

        public ComponentEntity()
        Construct an entity in the default workspace with an empty string The object is added to the workspace directory. as its name. Increment the version number of the workspace.
      • ComponentEntity

        public ComponentEntity​(Workspace workspace)
        Construct an entity in the specified workspace with 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. The object is added to the workspace directory. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace that will list the entity.
      • ComponentEntity

        public ComponentEntity​(CompositeEntity container,
                               java.lang.String name)
                        throws IllegalActionException,
                               NameDuplicationException
        Construct an entity with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This entity 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 constructor write-synchronizes on the workspace.
        Parameters:
        container - The container entity.
        name - The name of the entity.
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container.
        NameDuplicationException - If the name coincides with an entity already in the container.
    • Method Detail

      • clone

        public java.lang.Object clone​(Workspace workspace)
                               throws java.lang.CloneNotSupportedException
        Clone the object 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 new component entity that defers its definition to the same object as this one (or to none) that has no container.
        Overrides:
        clone in class Entity<T extends ComponentPort>
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new instance of ComponentEntity.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)
      • instantiate

        public Instantiable instantiate​(NamedObj container,
                                        java.lang.String name)
                                 throws java.lang.CloneNotSupportedException,
                                        IllegalActionException,
                                        NameDuplicationException
        Create an instance by cloning this object and then adjusting the parent-child relationships between the clone and its parent. Specifically, the clone defers its definition to this object, which becomes its "parent." It inherits all the objects contained by this object. If this object is a composite, then this method adjusts any deferral relationships that are entirely contained within the clone. That is, for any parent-child relationship that is entirely contained within this object (i.e., both the parent and the child are deeply contained by this object), a corresponding parent-child relationship is created within the clone such that both the parent and the child are entirely contained within the clone.

        The new object is not a class definition (it is by default an "instance" rather than a "class"). To make it a class definition (a "subclass"), call setClassDefinition(true).

        This method overrides the base class to use setContainer() to specify the container.

        Specified by:
        instantiate in interface Instantiable
        Overrides:
        instantiate in class InstantiableNamedObj
        Parameters:
        container - The container for the instance, or null to instantiate it at the top level.
        name - The name for the clone.
        Returns:
        A new instance that is a clone of this object with adjusted deferral relationships.
        Throws:
        java.lang.CloneNotSupportedException - If this object cannot be cloned.
        IllegalActionException - If this object is not a class definition or the proposed container is not acceptable.
        NameDuplicationException - If the name collides with an object already in the container.
        See Also:
        Entity.setClassDefinition(boolean)
      • isAtomic

        public boolean isAtomic()
        Return true if the entity is atomic. An atomic entity is one that cannot have components. Instances of this base class are always atomic. Derived classes that return false are assumed to be instances of CompositeEntity or a class derived from that.
        Returns:
        True if the entity is atomic.
        See Also:
        CompositeEntity
      • isOpaque

        public boolean isOpaque()
        Return true if the entity is opaque. An opaque entity is one that either is atomic or hides its components behind opaque ports. Instances of this base class are always opaque. Derived classes may be transparent, in which case they return false to this method and to isAtomic().
        Returns:
        True if the entity is opaque.
        See Also:
        CompositeEntity
      • moveDown

        public int moveDown()
                     throws IllegalActionException
        Move this object down by one in the list of entities of its container. If this object is already last, do nothing. Increment the version of the workspace.
        Specified by:
        moveDown in interface Moveable
        Overrides:
        moveDown in class NamedObj
        Returns:
        The index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - If this object has no container.
      • moveToFirst

        public int moveToFirst()
                        throws IllegalActionException
        Move this object to the first position in the list of entities of the container. If this object is already first, do nothing. Increment the version of the workspace.
        Specified by:
        moveToFirst in interface Moveable
        Overrides:
        moveToFirst in class NamedObj
        Returns:
        The index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - If this object has no container.
      • moveToIndex

        public int moveToIndex​(int index)
                        throws IllegalActionException
        Move this object to the specified position in the list of entities of the container. If this object is already at the specified position, do nothing. Increment the version of the workspace.
        Specified by:
        moveToIndex in interface Moveable
        Overrides:
        moveToIndex in class NamedObj
        Parameters:
        index - The position to move this object to.
        Returns:
        The index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - If this object has no container or if the index is out of bounds.
      • moveToLast

        public int moveToLast()
                       throws IllegalActionException
        Move this object to the last position in the list of entities of the container. If this object is already last, do nothing. Increment the version of the workspace.
        Specified by:
        moveToLast in interface Moveable
        Overrides:
        moveToLast in class NamedObj
        Returns:
        The index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - If this object has no container.
      • moveUp

        public int moveUp()
                   throws IllegalActionException
        Move this object up by one in the list of entities of the container. If this object is already first, do nothing. Increment the version of the workspace.
        Specified by:
        moveUp in interface Moveable
        Overrides:
        moveUp in class NamedObj
        Returns:
        The index of the specified object prior to moving it, or -1 if it is not moved.
        Throws:
        IllegalActionException - If this object has no container.
      • newPort

        public Port newPort​(java.lang.String name)
                     throws IllegalActionException,
                            NameDuplicationException
        Create a new port with the specified name. The container of the port is set to this entity. This overrides the base class to create an instance of ComponentPort. Derived classes may override this to further constrain the ports. This method is write-synchronized on the workspace and increments its version number.
        Overrides:
        newPort in class Entity<T extends ComponentPort>
        Parameters:
        name - The new port name.
        Returns:
        The new port
        Throws:
        IllegalActionException - If the argument is null.
        NameDuplicationException - If this entity already has a port with the specified name.
      • propagateExistence

        public java.util.List propagateExistence()
                                          throws IllegalActionException
        Propagate the existence of this object. If this object has a container, then ensure that all objects derived from the container contain an object with the same class and name as this one. Create that object when needed. Return the list of objects that are created. This overrides the base class to adjust deferrals within the objects that are created by cloning this one.
        Specified by:
        propagateExistence in interface Derivable
        Overrides:
        propagateExistence in class NamedObj
        Returns:
        A list of derived objects of the same class as this object that are created.
        Throws:
        IllegalActionException - If the object does not exists and cannot be created.
        See Also:
        Derivable, NamedObj.setDerivedLevel(int)
      • setContainer

        public void setContainer​(CompositeEntity container)
                          throws IllegalActionException,
                                 NameDuplicationException
        Specify the container, adding the entity to the list of entities in the container. If the container already contains an entity with the same name, then throw an exception and do not make any changes. Similarly, if the container is not in the same workspace as this entity, throw an exception. If this entity is a class element and the proposed container does not match the current container, then also throw an exception. If the entity is already contained by the container, do nothing. If this entity already has a container, remove it from that container first. Otherwise, remove it from the directory of the workspace, if it is present. If the argument is null, then unlink the ports of the entity from any relations and remove it from its container. It is not added to the workspace directory, so this could result in this entity being garbage collected.

        Note that for entities that are created by parsing MoML, it may be necessary to call MoMLParser.purgeModelRecord(). This is especially critical when the MoML file imports MoML classes. See Effigy.setContainer() for details.

        Derived classes may further constrain the container to subclasses of CompositeEntity by overriding the protected method _checkContainer(). This method validates all deeply contained instances of Settable, since they may no longer be valid in the new context. This method is write-synchronized to the workspace and increments its version number.

        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, or if the protected method _checkContainer() throws it, or if a contained Settable becomes invalid and the error handler throws it.
        NameDuplicationException - If the name of this entity collides with a name already in the container.
        See Also:
        getContainer()
      • _adjustDeferrals

        protected void _adjustDeferrals()
                                 throws IllegalActionException
        Adjust the deferrals in this object. This method should be called on any newly created object that is created by cloning. While cloning, parent relations are set to null. That is, no object in the clone has a parent. This method identifies the correct parent for any object in the clone. To do this, it uses the class name. Specifically, if this object has a class name that refers to a class in scope, then it replaces the current parent with that object. To look for a class in scope, we go up the hierarchy, but no more times than the return value of getDerivedLevel(). The reason for this is that if the class from which this object is defined is above that level, then we do not want to establish a parent relationship with that class. This object is implied, and the parent relationship of the object from which it is implied is sufficient.

        Derived classes that contain other objects should recursively call this method on contained objects.

        Throws:
        IllegalActionException - If the class found in scope cannot be set.
      • _checkContainer

        protected void _checkContainer​(InstantiableNamedObj container)
                                throws IllegalActionException
        Check the specified container.
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the container is not an instance of CompositeEntity, or if the proposed container is null and there are other objects that defer their definitions to this one.
      • _getContainedObject

        protected NamedObj _getContainedObject​(NamedObj container,
                                               java.lang.String relativeName)
                                        throws IllegalActionException
        Get an entity with the specified name in the specified container. The returned object is assured of being an instance of the same class as this object.
        Overrides:
        _getContainedObject in class NamedObj
        Parameters:
        relativeName - The name relative to the container.
        container - The container expected to contain the object, which must be an instance of CompositeEntity.
        Returns:
        An object of the same class as this object, or null if there is none.
        Throws:
        IllegalActionException - If the object exists and has the wrong class, or if the specified container is not an instance of CompositeEntity.
      • _propagateExistence

        protected NamedObj _propagateExistence​(NamedObj container)
                                        throws IllegalActionException
        Propagate existence of this object to the specified object. This overrides the base class to set the container.
        Overrides:
        _propagateExistence in class NamedObj
        Parameters:
        container - Object to contain the new object.
        Returns:
        A new object of the same class and name as this one.
        Throws:
        IllegalActionException - If the object cannot be cloned.