Package ptolemy.kernel

Class Entity<T extends Port>

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    AttributeChanged, ComponentEntity, PortHasNoContainer, PortNameProblem
    public class Entity<T extends Port>
extends InstantiableNamedObj
    An Entity is a vertex in a generalized graph. It is an aggregation of ports. The ports can be linked to relations. The relations thus represent connections between ports, and hence, connections between entities. To add a port to an entity, simply set its container to the entity. To remove it, set its container to null, or to some other entity.

    Entities are intended for flat graphs. Derived classes support hierarchy (clustered graphs) by defining entities that aggregate other entities.

    An Entity can contain any instance of Port. Derived classes may wish to constrain to a subclass of Port. To do this, subclasses 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.

    An Entity is created within a workspace. If the workspace is not specified as a constructor argument, then the default workspace is used. The workspace is used to synchronize simultaneous accesses to a topology from multiple threads. The workspace is immutable (it cannot be changed during the lifetime of the Entity).

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    John S. Davis II, Edward A. Lee
    See Also:
    Port, Relation
    Pt.AcceptedRating:
    Green (johnr)
    Pt.ProposedRating:
    Green (eal)

    • Constructor Detail

      • Entity

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

      • Entity

        public Entity​(java.lang.String name)
       throws IllegalActionException
        Construct an entity in the default workspace with the given name. 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 number of the workspace.
        Parameters:
        name - The name of this object.
        Throws:
        IllegalActionException - If the name has a period.

      • Entity

        public Entity​(Workspace workspace)
        Construct an entity 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.

      • Entity

        public Entity​(Workspace workspace,
              java.lang.String name)
       throws IllegalActionException
        Construct an entity 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 - The workspace for synchronization and version tracking.
        name - The 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 entity with clones of the ports of the original entity. The ports are set to the ports of the new entity. This method gets read access on the workspace associated with this object.
        Overrides:
        clone in class InstantiableNamedObj
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new Entity.
        Throws:
        java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • connectedPortList

        public java.util.List<T> connectedPortList()
        Return a list of the ports that are connected to contained ports. Ports in this entity are not included unless there is a loopback, meaning that two distinct ports of this entity are linked to the same relation. The connected entities can be obtained from the ports using getContainer(). Note that a port may be listed more than once if there is more than one connection to it. This method is read-synchronized on the workspace.
        Returns:
        An unmodifiable list of Port objects.

      • connectedPorts

        @Deprecated
public java.util.Enumeration connectedPorts()
        Deprecated.
        Use connectedPortList() instead.
        Enumerate all ports that are connected to contained ports. Ports in this entity are not included unless there is a loopback, meaning that two distinct ports of this entity are linked to the same relation. The connected entities can be obtained from the ports using getContainer(). Note that a port may be listed more than once if there is more than one connection to it. This method is read-synchronized on the workspace.
        Returns:
        An enumeration of Port objects.

      • connectionsChanged

        public void connectionsChanged​(Port port)
        Notify this entity that the links to the specified port have been altered. The default implementation in this base class is to do nothing, but derived classes may want to react to new connections.
        Parameters:
        port - The port to which connections have changed.

      • containedObjectsIterator

        public java.util.Iterator containedObjectsIterator()
        Return an iterator over contained objects. In this class, this is simply an iterator over attributes and ports. In derived classes, the iterator will also traverse classes, entities, and relations. The caller of this method should have read access on the workspace and hold it for the duration of the use of the iterator. Moreover, it should not modify the port or attribute list while using the iterator or it will get a ConcurrentModificationException.
        Overrides:
        containedObjectsIterator in class NamedObj
        Returns:
        An iterator over instances of NamedObj contained by this object.

      • getAttribute

        public Attribute getAttribute​(java.lang.String name)
        Get the attribute with the given name. The name may be compound, with fields separated by periods, in which case the attribute returned is (deeply) contained by a contained attribute or port. This method is read-synchronized on the workspace.
        Overrides:
        getAttribute in class NamedObj
        Parameters:
        name - The name of the desired attribute.
        Returns:
        The requested attribute if it is found, null otherwise.

      • getPort

        public Port getPort​(java.lang.String name)
        Return the port contained by this entity that has the specified name. If there is no such port, return null. This method is read-synchronized on the workspace.
        Parameters:
        name - The name of the desired port.
        Returns:
        A port with the given name, or null if none exists.

      • getPorts

        @Deprecated
public java.util.Enumeration getPorts()
        Deprecated.
        Use portList() instead.
        Enumerate the ports belonging to this entity. The order is the order in which they became contained by this entity. This method is read-synchronized on the workspace.
        Returns:
        An enumeration of Port objects.

      • linkedRelationList

        public java.util.List linkedRelationList()
        Get all relations that are linked to ports contained by this entity. Note that a relation may be listed more than once. This method is read-synchronized on the workspace.
        Returns:
        An unmodifiable list of Relation objects.

      • linkedRelations

        @Deprecated
public java.util.Enumeration linkedRelations()
        Deprecated.
        Use linkedRelationList() instead.
        Enumerate relations that are linked to ports contained by this entity. Note that a relation may be listed more than once. This method is read-synchronized on the workspace.
        Returns:
        An enumeration of Relation objects.

      • newPort

        public Port newPort​(java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException
        Create a new port with the specified name. Set its container to be this entity. Derived classes should override this method to create a subclass of Port, if they require subclasses of Port. If the name argument is null, then the name used is an empty string. This method is write-synchronized on the workspace, and increments its version number.
        Parameters:
        name - The name to assign to the newly created port.
        Returns:
        The new port.
        Throws:
        IllegalActionException - If the port created is not of an acceptable class (this is a programming error; failed to override this method in derived classes).
        NameDuplicationException - If the entity already has a port with the specified name.

      • portList

        public java.util.List<T> portList()
        Get the ports belonging to this entity. The order is the order in which they became contained by this entity. This method is read-synchronized on the workspace.
        Returns:
        An unmodifiable list of Port objects.

      • removeAllPorts

        public void removeAllPorts()
        Remove all ports by setting their container to null. As a side effect, the ports will be unlinked from all relations. This method is write-synchronized on the workspace, and increments its version number.

      • uniqueName

        public java.lang.String uniqueName​(java.lang.String prefix)
        Return a name that is guaranteed to not be the name of any contained attribute or port. In derived classes, this should be overridden so that the returned name is guaranteed to not conflict with any contained object. In this implementation, the argument is stripped of any numeric suffix, and then a numeric suffix is appended and incremented until a name is found that does not conflict with a contained attribute or port.
        Overrides:
        uniqueName in class NamedObj
        Parameters:
        prefix - A prefix for the name.
        Returns:
        A unique name.

      • _addPort

        protected void _addPort​(T port)
                 throws IllegalActionException,
                        NameDuplicationException
        Add a port to this entity. This method should not be used directly. Call the setContainer() method of the port instead. This method does not set the container of the port to point to this entity. It assumes that the port is in the same workspace as this entity, but does not check. The caller should check. Derived classes should override this method if they require a subclass of Port to throw an exception if the argument is not of an acceptable class. This method is not synchronized on the workspace, so the caller should be.
        Parameters:
        port - The port to add to this entity.
        Throws:
        IllegalActionException - If the port has no name.
        NameDuplicationException - If the port name collides with a name already in the entity.

      • _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 there is a problem accessing subcomponents of this object.

      • _exportMoMLContents

        protected void _exportMoMLContents​(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException
        Write a MoML description of the contents of this object, which in this class are the attributes plus the ports. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.
        Overrides:
        _exportMoMLContents in class NamedObj
        Parameters:
        output - The output to write to.
        depth - The depth in the hierarchy, to determine indenting.
        Throws:
        java.io.IOException - If an I/O error occurs.
        See Also:
        NamedObj.exportMoML(Writer, int)

      • _removePort

        protected void _removePort​(Port port)
        Remove the specified port. This method should not be used directly. Call the setContainer() method of the port instead with a null argument. The port is assumed to be contained by this entity (otherwise, nothing happens). This method does not alter the container of the port. This method is not synchronized on the workspace, so the caller should be.
        Parameters:
        port - The port being removed from this entity.

      • _validateSettables

        protected void _validateSettables​(java.util.Collection attributesValidated)
                           throws IllegalActionException
        Validate attributes deeply contained by this object if they implement the Settable interface by calling their validate() method. This method overrides the base class to check attributes contained by the contained ports. Errors that are triggered by this validation are handled by calling handleModelError().
        Overrides:
        _validateSettables in class NamedObj
        Parameters:
        attributesValidated - A HashSet of Attributes that have already been validated. For example, Settables that implement the SharedSettable interface are validated only once.
        Throws:
        IllegalActionException - If the superclass throws it or if handleModelError() throws it.
        See Also:
        NamedObj.handleModelError(NamedObj context, IllegalActionException exception)