Package ptolemy.kernel

Class Relation

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ComponentRelation
    public class Relation
extends NamedObj
    A Relation links ports, and therefore the entities that contain them. To link a port to a relation, use the link() method in the Port class. To remove a link, use the unlink() method in the Port class.

    Relations can also be linked to other Relations. To create such a link, use the link() method of this class. To remove such a link, use the unlink() method. A group of linked relations behaves exactly as if it were one relation directly linked to all the ports linked to by each relation. In particular, the connectedPortList() method of the Port class returns the same list whether a single relation is used or a relation group. The order in which the ports are listed is the order in which links were made between the port and relations in the relation group. It is not relevant which relation in a relation group the port links to.

    Derived classes may wish to disallow links under certain circumstances, for example if the proposed port is not an instance of an appropriate subclass of Port, or if the relation cannot support any more links. Such derived classes should override the protected method _checkPort() or _checkRelation() to throw an exception.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Edward A. Lee, Neil Smyth
    See Also:
    Port, Entity
    Pt.AcceptedRating:
    Green (acataldo)
    Pt.ProposedRating:
    Green (eal)

    • Field Detail

      • _linkList

        protected CrossRefList _linkList
        The list of Ports and Relations that are linked to this Relation.

    • Constructor Detail

      • Relation

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

      • Relation

        public Relation​(java.lang.String name)
         throws IllegalActionException
        Construct a relation in the default workspace with the given name. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace. The object is added to the workspace directory.
        Parameters:
        name - Name of this object.
        Throws:
        IllegalActionException - If the name has a period.

      • Relation

        public Relation​(Workspace workspace)
        Construct a relation in the given workspace with an empty string as a name. If the workspace argument is null, use the default workspace. The object is added to the workspace directory. Increment the version of the workspace.
        Parameters:
        workspace - The workspace for synchronization and version tracking.

      • Relation

        public Relation​(Workspace workspace,
                java.lang.String name)
         throws IllegalActionException
        Construct a relation in the given workspace with the given name. If the workspace argument is null, use the default workspace. If the name argument is null, then the name is set to the empty string. The object is added to the workspace directory. Increment the version of the workspace.
        Parameters:
        workspace - Workspace for synchronization and version tracking
        name - Name of this object.
        Throws:
        IllegalActionException - If the name has a period.

    • 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 NamedObj
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new Relation.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • link

        public void link​(Relation relation)
          throws IllegalActionException
        Link this relation with another relation. The relation is required to be at the same level of the hierarchy as this relation. That is, level-crossing links are not allowed. If the specified relation is already linked to this one, do nothing. In derived classes, the relation may be required to be an instance of a particular subclass of Relation (this is checked by the _checkRelation() protected method). This method is write-synchronized on the workspace and increments its version number.
        Parameters:
        relation - The relation to link to this relation.
        Throws:
        IllegalActionException - If the link would cross levels of the hierarchy, or the relation is incompatible, or this relation has no container, or this relation is not in the same workspace as the relation.

      • linkedObjectsList

        public java.util.List linkedObjectsList()
        Return a list of the objects directly linked to this relation (ports and relations). Note that a port may appear more than once if more than one link to it has been established, but a relation will appear only once. There is no significance to multiple links between the same relations. This method is read-synchronized on the workspace.
        Returns:
        A list of Port and Relation objects.

      • linkedPortList

        public java.util.List linkedPortList()
        List the ports linked to any relation in this relation's group. Note that a port may appear more than once if more than one link to it has been established. The order in which ports are listed has no significance. This method is read-synchronized on the workspace.
        Returns:
        A list of Port objects.

      • linkedPortList

        public java.util.List linkedPortList​(Port except)
        List the ports linked to any relation in this relation's group except the specified port. Note that a port may appear more than once if more than on link to it has been established. The order in which ports are listed has no significance. This method is read-synchronized on the workspace.
        Parameters:
        except - Port to exclude from the list.
        Returns:
        A list of Port objects.

      • linkedPorts

        @Deprecated
public java.util.Enumeration linkedPorts()
        Deprecated.
        Use linkedPortList() instead.
        Enumerate the linked ports. Note that a port may appear more than once if more than one link to it has been established. This method is read-synchronized on the workspace.
        Returns:
        An Enumeration of Port objects.

      • linkedPorts

        @Deprecated
public java.util.Enumeration linkedPorts​(Port except)
        Deprecated.
        Use linkedPortList(Port) instead.
        Enumerate the linked ports except the specified port. Note that a port may appear more than once if more than on link to it has been established. This method is read-synchronized on the workspace.
        Parameters:
        except - Port to exclude from the enumeration.
        Returns:
        An Enumeration of Port objects.

      • numLinks

        public int numLinks()
        Return the number of links to ports, either directly or indirectly via other relations in the relation group. This is the size of the list returned by linkedPortList(). This method is read-synchronized on the workspace.
        Returns:
        The number of links.
        See Also:
        linkedPortList()

      • relationGroupList

        public java.util.List relationGroupList()
        Return the list of relations in the relation group containing this relation. The relation group includes this relation, all relations directly linked to it, all relations directly linked to those, etc. That is, it is a maximal set of linked relations. There is no significance to the order of the returned list, but the returned value is a List rather than a Set to facilitate testing.
        Returns:
        The relation group.

      • unlink

        public void unlink​(Relation relation)
        Unlink the specified Relation. If the Relation is not linked to this relation, do nothing. This method is write-synchronized on the workspace and increments its version number.
        Parameters:
        relation - The relation to unlink.

      • unlinkAll

        public void unlinkAll()
        Unlink all ports and relations that are directly linked to this relation. This method is write-synchronized on the workspace and increments its version number.

      • _checkPort

        protected void _checkPort​(Port port)
                   throws IllegalActionException
        Throw an exception if the specified port cannot be linked to this relation. In this base class, the exception is not thrown, but in derived classes, it might be, for example if the relation cannot support any more links, or the port is not an instance of an appropriate subclass of Port.
        Parameters:
        port - The port to link to.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _checkRelation

        protected void _checkRelation​(Relation relation,
                              boolean symmetric)
                       throws IllegalActionException
        Check that this relation is compatible with the specified relation. In this base class, this method calls the corresponding check method of the specified relation, and if that returns, then it returns. Derived classes should override this method to check validity of the specified relation, and then call super._checkRelation().
        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 relation has no container, or if this relation is not an acceptable relation for the specified relation.

      • _description

        protected java.lang.String _description​(int detail,
                                        int indent,
                                        int bracket)
                                 throws IllegalActionException
        Return a description of the object. The level of detail depends on the argument, which is an or-ing of the static final constants defined in the NamedObj class. Lines are indented according to to the level argument using the protected method _getIndentPrefix(). Zero, one or two brackets can be specified to surround the returned description. If one is specified it is the the leading bracket. This is used by derived classes that will append to the description. Those derived classes are responsible for the closing bracket. An argument other than 0, 1, or 2 is taken to be equivalent to 0. This method is read-synchronized on the workspace.
        Overrides:
        _description in class NamedObj
        Parameters:
        detail - The level of detail.
        indent - The amount of indenting.
        bracket - The number of surrounding brackets (0, 1, or 2).
        Returns:
        A description of the object.
        Throws:
        IllegalActionException - If thrown while getting the description of subcomponents.

      • _getContainedObject

        protected NamedObj _getContainedObject​(NamedObj container,
                                       java.lang.String relativeName)
                                throws IllegalActionException
        Get a relation 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.