Class ComponentRelation

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ConceptRelation, IORelation, TestComponentRelation, Transition

    public class ComponentRelation
    extends Relation
    This class defines a relation supporting hierarchy (clustered graphs). Specifically, a method is added for defining a container and for performing deep traversals of a graph. Most importantly, however, instances of this class refuse to link to ports that are not instances of ComponentPort. Thus, this class ensures that ComponentPort instances are only connected to other ComponentPort instances.

    Derived classes may wish to further constrain linked ports to a subclass of ComponentPort, or to disallow links under other circumstances, for example if the relation cannot support any more links. Such derived classes should override the protected method _checkPort() to throw an exception.

    To link a ComponentPort to a ComponentRelation, use the link() or liberalLink() method in the ComponentPort class. To remove a link, use the unlink() method.

    The container for instances of this class can only be instances of ComponentEntity. Derived classes may wish to further constrain the container to subclasses of ComponentEntity. To do this, they should override the protected _checkContainer() method.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Green (johnr)
    Pt.ProposedRating:
    Green (eal)
    • Constructor Detail

      • ComponentRelation

        public ComponentRelation()
        Construct a relation in the default workspace with an empty string as its name. Add the relation to the directory of the workspace.
      • ComponentRelation

        public ComponentRelation​(Workspace workspace)
        Construct a relation 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. Add the relation to the workspace directory.
        Parameters:
        workspace - The workspace that will list the relation.
      • ComponentRelation

        public ComponentRelation​(CompositeEntity container,
                                 java.lang.String name)
                          throws IllegalActionException,
                                 NameDuplicationException
        Construct a relation with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This relation 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. This constructor write-synchronizes on the workspace.
        Parameters:
        container - The container.
        name - The name of the relation.
        Throws:
        IllegalActionException - If the container is incompatible with this relation.
        NameDuplicationException - If the name coincides with a relation 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 relation with no links and no container.
        Overrides:
        clone in class Relation
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new ComponentRelation.
        Throws:
        java.lang.CloneNotSupportedException - If one or more of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)
      • deepLinkedPortList

        public java.util.List deepLinkedPortList()
        Deeply list the ports linked to this relation. Look through all transparent ports and return only opaque ports. This method is read-synchronized on the workspace.
        Returns:
        An unmodifiable list of ComponentPorts.
      • deepLinkedPorts

        @Deprecated
        public java.util.Enumeration deepLinkedPorts()
        Deprecated.
        Use deepLinkedPortList() instead.
        Deeply enumerate the ports linked to this relation. Look through all transparent ports and return only opaque ports. This method is read-synchronized on the workspace.
        Returns:
        An enumeration of ComponentPorts.
      • moveDown

        public int moveDown()
                     throws IllegalActionException
        Move this object down by one in the list of relations 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 relations 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 relations 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 relations 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 relations 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.
      • setContainer

        public void setContainer​(CompositeEntity container)
                          throws IllegalActionException,
                                 NameDuplicationException
        Specify the container entity, adding the relation to the list of relations in the container. If the container already contains a relation 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 relation, throw an exception. If the relation is a class element and the proposed container does not match the current container, then also throw an exception. If the relation is already contained by the container, do nothing. If this relation already has a container, remove it from that container first. Otherwise, remove it from the workspace directory, if it is present. If the argument is null, then unlink the ports from the relation and remove it from its container. It is not added to the workspace directory, so this could result in this relation being garbage collected. Derived classes may further constrain the class of the container to a subclass of CompositeEntity. 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 on the workspace and increments its version number.
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If this entity and the container are not in the same workspace, or if a contained Settable becomes invalid and the error handler throws it.
        NameDuplicationException - If the name collides with a name already on the contents list of the container.
        See Also:
        getContainer()
      • unlinkAll

        public void unlinkAll()
        Override the base class to break inside links on ports as well as outside lists. This method is write-synchronized on the workspace and increments its version number.
        Overrides:
        unlinkAll in class Relation
      • _checkContainer

        protected void _checkContainer​(CompositeEntity container)
                                throws IllegalActionException
        Check that the specified container is of a suitable class for this relation. In this base class, this method returns immediately without doing anything.
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the container is not of an acceptable class. Not thrown in this base class.
      • _checkPort

        protected void _checkPort​(Port port)
                           throws IllegalActionException
        Throw an exception if the specified port cannot be linked to this relation (is not of class ComponentPort).
        Overrides:
        _checkPort in class Relation
        Parameters:
        port - The port to link to.
        Throws:
        IllegalActionException - If the port is not a ComponentPort.
      • _checkRelation

        protected void _checkRelation​(Relation relation,
                                      boolean symmetric)
                               throws IllegalActionException
        Throw an exception if the specified relation is not an instance of ComponentRelation.
        Overrides:
        _checkRelation in class Relation
        Parameters:
        relation - The relation to link to.
        symmetric - If true, the call _checkRelation on the specified relation with this as an argument.
        Throws:
        IllegalActionException - If this port has no container, or if this port is not an acceptable port for the specified relation.
      • _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.