Package ptolemy.actor

Class TypedIOPort

  • All Implemented Interfaces:
    java.lang.Cloneable, HasTypeConstraints, Typeable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    Assert.AssertPort, CPort, DDEIOPort, MirrorPort, ModalBasePort, MultiCompositePort, ParameterPort, PortMatcher, PubSubPort, QueuedTypedIOPort, RefinementPort, SDFIOPort, TDLTaskPort, WirelessIOPort
    public class TypedIOPort
extends IOPort
implements Typeable
    An IOPort with a type. This class implements the Typeable interface. The type is represented by an instance of Type in data.type package. It can be declared by calling setTypeEquals(). If this method is not called, or called with a BaseType.UNKNOWN argument, the type of this port will be set by type resolution using the type constraints. The type constraints on this port can be specified using the methods defined in the Typeable interface.

    This class keeps a list of TypeListeners. Whenever the type changes, this class will generate an instance of TypeEvent and pass it to the listeners by calling their typeChanged() method. A TypeListener register its interest in the type change event of this port by calling addTypeListener(), and can be removed from the listener list by calling the removeTypeListener().

    A TypedIOPort can only link to instances of TypedIORelation. Derived classes may further constrain links to a subclass of TypedIORelation. To do this, they should override the protected methods _link() and _linkInside() to throw an exception if their arguments are not of the appropriate type. Similarly, an TypeIOPort can only be contained by a class derived from ComponentEntity and implementing the TypedActor interface. Subclasses may further constrain the containers by overriding _checkContainer().

    Note that actors that call some of the setTypeXXX methods may also need to have a clone() method. Although the base classes neatly handle most aspects of the clone operation, there are subtleties involved with cloning type constraints. Absolute type constraints on ports and parameters are carried automatically into the clone, so clone() methods should never call setTypeEquals(). However, relative type constraints of the other setTypeXXX() methods are not cloned automatically because of the difficulty of ensuring that the other object being referred to in a relative constraint is the intended one.

    For example the Ramp actor constructor calls: 

     output.setTypeAtLeast(init);
    so the clone() method of the Ramp actor calls: 
     newObject.output.setTypeAtLeast(newObject.init);
    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Yuhong Xiong, Lukito Muliadi
    Pt.AcceptedRating:
    Yellow (neuendor)
    Pt.ProposedRating:
    Green (yuhong)

    • Field Detail

      • TYPE

        public static final int TYPE
        Indicate that the description(int) method should include information about the type of this port.
        See Also:
        Constant Field Values

      • _resolvedType

        protected Type _resolvedType
        The resolved type of the port. The value of this variable is set when the InequalityTerm methods initialize(Object), setTypeEquals(), and setValue(Object) are called.

    • Constructor Detail

      • TypedIOPort

        public TypedIOPort()
        Construct a TypedIOPort with no container and no name that is neither an input nor an output.

      • TypedIOPort

        public TypedIOPort​(Workspace workspace)
            throws IllegalActionException
        Construct a port 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 port.
        Throws:
        IllegalActionException - If thrown by the superclass.

      • TypedIOPort

        public TypedIOPort​(ComponentEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException
        Construct a TypedIOPort with a containing actor and a name that is neither an input nor an output. The specified container must implement the TypedActor interface, or an exception will be thrown.
        Parameters:
        container - The container actor.
        name - The name of the port.
        Throws:
        IllegalActionException - If the port is not of an acceptable class for the container, or if the container does not implement the TypedActor interface.
        NameDuplicationException - If the name coincides with a port already in the container.

      • TypedIOPort

        public TypedIOPort​(ComponentEntity container,
                   java.lang.String name,
                   boolean isInput,
                   boolean isOutput)
            throws IllegalActionException,
                   NameDuplicationException
        Construct a TypedIOPort with a container and a name that is either an input, an output, or both, depending on the third and fourth arguments. The specified container must implement the TypedActor interface or an exception will be thrown.
        Parameters:
        container - The container actor.
        name - The name of the port.
        isInput - True if this is to be an input port.
        isOutput - True if this is to be an output port.
        Throws:
        IllegalActionException - If the port is not of an acceptable class for the container, or if the container does not implement the TypedActor interface.
        NameDuplicationException - If the name coincides with a port already in the container.

    • Method Detail

      • addTypeListener

        public void addTypeListener​(TypeListener listener)
        Add a type listener to this port. The listener will be notified of all the type changes. If the listener is already listening to this port, then do nothing.
        Parameters:
        listener - The TypeListener to add.
        See Also:
        removeTypeListener(TypeListener)

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        React to a change in an attribute. This method is called by a contained attribute when its value changes. This overrides the base class so that if the attribute is an instance of TypeAttribute, then it sets the type of the port.
        Overrides:
        attributeChanged in class IOPort
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container.

      • broadcast

        public void broadcast​(Token token)
               throws IllegalActionException,
                      NoRoomException
        Send a token to all connected receivers. Tokens are in general immutable, so each receiver is given a reference to the same token and no clones are made. The transfer is accomplished by calling getRemoteReceivers() to determine the number of channels with valid receivers and then calling send() on the appropriate channels. It would probably be faster to call put() directly on the receivers. If there are no destination receivers, then nothing is sent. If the port is not connected to anything, or receivers have not been created in the remote port, then just return.

        Some of this method is read-synchronized on the workspace. Since it is possible for a thread to block while executing a put, it is important that the thread does not hold read access on the workspace when it is blocked. Thus this method releases read access on the workspace before calling put.

        Overrides:
        broadcast in class IOPort
        Parameters:
        token - The token to send
        Throws:
        IllegalActionException - If the token to be sent cannot be converted to the type of this port
        NoRoomException - If a send to one of the channels throws it.

      • broadcast

        public void broadcast​(Token[] tokenArray,
                      int vectorLength)
               throws IllegalActionException,
                      NoRoomException
        Send the specified portion of a token array to all receivers connected to this port. The first vectorLength tokens of the token array are sent.

        Tokens are in general immutable, so each receiver is given a reference to the same token and no clones are made. If the port is not connected to anything, or receivers have not been created in the remote port, or the channel index is out of range, or the port is not an output port, then just silently return. This behavior makes it easy to leave output ports unconnected when you are not interested in the output. The transfer is accomplished by calling the vectorized put() method of the remote receivers. If the port is not connected to anything, or receivers have not been created in the remote port, then just return.

        Some of this method is read-synchronized on the workspace. Since it is possible for a thread to block while executing a put, it is important that the thread does not hold read access on the workspace when it is blocked. Thus this method releases read access on the workspace before calling put.

        Overrides:
        broadcast in class IOPort
        Parameters:
        tokenArray - The token array to send
        vectorLength - The number of elements of the token array to send.
        Throws:
        NoRoomException - If there is no room in the receiver.
        IllegalActionException - If the tokens to be sent cannot be converted to the type of this port

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone this port into the specified workspace. The new port is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new port with no connections and no container. The new port will have the same type as this one, but will not have any type listeners and type constraints attached to it.
        Overrides:
        clone in class IOPort
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new TypedIOPort.
        Throws:
        java.lang.CloneNotSupportedException - If one or more of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • convert

        public Token convert​(Token token)
              throws IllegalActionException
        Convert the specified token into a token with type equal to the type returned by getType(). If the token is already of this type, then simply return the specified token.
        Overrides:
        convert in class IOPort
        Parameters:
        token - The token to convert.
        Returns:
        The converted token.
        Throws:
        IllegalActionException - If the conversion is invalid.

      • getType

        public Type getType()
        Return the type of this port. If this port is opaque, this method returns the resolved type of this port; if this port is a transparent input port, this method returns the greatest lower bound of the types of the inside ports; if this port is a transparent output port, this method returns the least upper bound of the types of the inside ports. This method is read-synchronized on the workspace.
        Specified by:
        getType in interface Typeable
        Returns:
        An instance of Type.

      • getTypeTerm

        public InequalityTerm getTypeTerm()
        Return an InequalityTerm encapsulating the type of this port. The InequalityTerm can be used to form type constraints. If the type is set through setTypeEquals(), the inequality term represents a type constant; otherwise, it represents a type variable.
        Specified by:
        getTypeTerm in interface Typeable
        Returns:
        An InequalityTerm whose value is the type of this port.

      • isTypeAcceptable

        public boolean isTypeAcceptable()
        Check whether the current type of this port is acceptable. A type is acceptable if it represents an instantiable object. Any type is acceptable (including non-instantiable types) if the associated port is not connected to anything.
        Specified by:
        isTypeAcceptable in interface Typeable
        Returns:
        True if the current type is acceptable.

      • getAutomaticTypeConversion

        public boolean getAutomaticTypeConversion()
        Indicates whether conversion of received tokens is enabled or not.
        Returns:
        True if conversion is enabled, or false otherwise.
        See Also:
        setAutomaticTypeConversion(boolean)

      • removeTypeListener

        public void removeTypeListener​(TypeListener listener)
        Remove a type listener from this port. If the listener is not attached to this port, do nothing.
        Parameters:
        listener - The TypeListener to be removed.
        See Also:
        addTypeListener(TypeListener)

      • send

        public void send​(int channelIndex,
                 Token token)
          throws IllegalActionException,
                 NoRoomException
        Send a token to the specified channel, checking the type and converting the token if necessary. If the port is not connected to anything, or receivers have not been created in the remote port, or the channel index is out of range, or the port is not an output port, then just silently return. This behavior makes it easy to leave output ports unconnected when you are not interested in the output. If the type of the specified token is the type of this port, or the token can be converted to that type losslessly, the token is sent to all receivers connected to the specified channel. Otherwise, IllegalActionException is thrown. Before putting the token into the destination receivers, this method also checks the type of the remote input port, and converts the token if necessary. The conversion is done by calling the convert() method of the type of the remote input port.

        If the token argument is null, then no token is sent. What this means exactly is domain dependent. In some domains (SR, Continuous), it asserts that the output is "absent." That is, IOPort.isKnown(int) will return true and IOPort.hasToken(int) will return false. In other domains (SDF, DE, PN), it simply does nothing. Nothing is sent. Hence, IOPort.isKnown(int) and IOPort.hasToken(int) will return whatever they would have returned before the call.

        Some of this method is read-synchronized on the workspace. Since it is possible for a thread to block while executing a put, it is important that the thread does not hold read access on the workspace when it is blocked. Thus this method releases read access on the workspace before calling put.

        Overrides:
        send in class IOPort
        Parameters:
        channelIndex - The index of the channel, from 0 to width-1.
        token - The token to send, or null to send no token.
        Throws:
        IllegalActionException - If the token to be sent cannot be converted to the type of this port, or if the token is null.
        NoRoomException - If there is no room in the receiver.

      • send

        public void send​(int channelIndex,
                 Token[] tokenArray,
                 int vectorLength)
          throws IllegalActionException,
                 NoRoomException
        Send the specified portion of a token array to all receivers connected to the specified channel, checking the type and converting the token if necessary. The first vectorLength tokens of the token array are sent. If the port is not connected to anything, or receivers have not been created in the remote port, or the channel index is out of range, or the port is not an output port, then just silently return. This behavior makes it easy to leave output ports unconnected when you are not interested in the output.

        If the type of the tokens in the specified portion of the token array is the type of this port, or the tokens in the specified portion of the token array can be converted to that type losslessly, the tokens in the specified portion of the token array are sent to all receivers connected to the specified channel. Otherwise, IllegalActionException is thrown. Before putting the tokens in the specified portion of the token array into the destination receivers, this method also checks the type of the remote input port, and converts the tokens if necessary. The conversion is done by calling the convert() method of the type of the remote input port.

        Some of this method is read-synchronized on the workspace. Since it is possible for a thread to block while executing a put, it is important that the thread does not hold read access on the workspace when it is blocked. Thus this method releases read access on the workspace before calling put.

        Overrides:
        send in class IOPort
        Parameters:
        channelIndex - The index of the channel, from 0 to width-1
        tokenArray - The token array to send
        vectorLength - The number of elements of the token array to send.
        Throws:
        NoRoomException - If there is no room in the receiver.
        IllegalActionException - If the tokens to be sent cannot be converted to the type of this port, or if the vectorLength argument is greater than the length of the tokenArray argument.

      • sendInside

        public void sendInside​(int channelIndex,
                       Token token)
                throws IllegalActionException,
                       NoRoomException
        Send the specified token to all receivers connected to the specified inside channel of this port, checking the type and converting the token if necessary. Tokens are in general immutable, so each receiver is given a reference to the same token and no clones are made. If the port is not connected to anything on the inside, or receivers have not been created in the remote port, or the channel index is out of range, or the port is not an input port, then just silently return. This behavior makes it easy to leave external input ports of a composite unconnected when you are not interested in the received values. The transfer is accomplished by calling the put() method of the inside remote receivers. If the port is not connected to anything, or receivers have not been created in the remote port, then just return. This method is normally called only by the transferInputs method of directors of composite actors, as AtomicActors do not usually have any relations on the inside of their ports. Before putting the token into the destination receivers, this method also checks the type of the inside input port, and converts the token if necessary. The conversion is done by calling the convert() method of the type of the inside input port.

        If the token argument is null, then no token is sent. What this means exactly is domain dependent. In some domains (SR, Continuous), it asserts that the output is "absent." That is, IOPort.isKnown(int) will return true and IOPort.hasToken(int) will return false. In other domains (SDF, DE, PN), it simply does nothing. Nothing is sent. Hence, IOPort.isKnown(int) and IOPort.hasToken(int) will return whatever they would have returned before the call.

        Some of this method is read-synchronized on the workspace. Since it is possible for a thread to block while executing a put, it is important that the thread does not hold read access on the workspace when it is blocked. Thus this method releases read access on the workspace before calling put.

        Overrides:
        sendInside in class IOPort
        Parameters:
        channelIndex - The index of the channel, from 0 to width-1
        token - The token to send
        Throws:
        NoRoomException - If there is no room in the receiver.
        IllegalActionException - If conversion to the type of the destination port cannot be done.

      • setAutomaticTypeConversion

        public void setAutomaticTypeConversion​(boolean automaticTypeConversion)
        Allow actors to disable automatic type conversion on their input ports in case they do not need it. For example, AddSubtract and Display accept any token type, because they make use of methods that are inherited by all token types. Disabling automatic type conversion lets actors use Java's dynamic dispatch mechanism instead. If set to false, received tokens will not be converted.
        Parameters:
        automaticTypeConversion - False in order to disable conversion of received tokens, true otherwise.
        See Also:
        getAutomaticTypeConversion()

      • setTypeAtLeast

        public void setTypeAtLeast​(Typeable lesser)
        Constrain the type of this port to be equal to or greater than the type of the specified Typeable object.

        Actors that call this method should have a clone() method that repeats the relative type constraints that were specified in the constructor.

        Specified by:
        setTypeAtLeast in interface Typeable
        Parameters:
        lesser - A Typeable object.

      • setTypeAtLeast

        public void setTypeAtLeast​(InequalityTerm typeTerm)
        Constrain the type of this port to be equal to or greater than the type represented by the specified InequalityTerm.

        Actors that call this method should have a clone() method that repeats the relative type constraints that were specified in the constructor.

        Specified by:
        setTypeAtLeast in interface Typeable
        Parameters:
        typeTerm - An InequalityTerm.

      • setTypeAtMost

        public void setTypeAtMost​(Type type)
        Constrain the type of this port to be equal to or less than the argument.

        Actors that call this method should have a clone() method that repeats the relative type constraints that were specified in the constructor.

        Specified by:
        setTypeAtMost in interface Typeable
        Parameters:
        type - An instance of Type.

      • setTypeEquals

        public void setTypeEquals​(Type type)
        Set the type of this port. The type is represented by an instance of Type. If the type is BaseType.UNKNOWN, the determination of the type is left to type resolution.

        Actors that call setTypeEquals() are not required to have a clone() method. Absolute type constraints on ports and parameters are carried automatically into the clone, so clone() methods of actors should never call setTypeEquals(). Actors that call the other setTypeXXX() methods should have a clone() method.

        This method is write-synchronized on the workspace.

        Specified by:
        setTypeEquals in interface Typeable
        Parameters:
        type - A Type.

      • setTypeSameAs

        public void setTypeSameAs​(Typeable equal)
        Constrain the type of this port to be the same as the type of the specified Typeable object.

        Actors that call this method should have a clone() method that repeats the relative type constraints that were specified in the constructor.

        Specified by:
        setTypeSameAs in interface Typeable
        Parameters:
        equal - A Typeable object.

      • typeConstraints

        public java.util.Set<Inequality> typeConstraints()
        Return the type constraints of this port in the form of a set of inequalities.
        Specified by:
        typeConstraints in interface HasTypeConstraints
        Returns:
        A set of inequalities.
        See Also:
        Inequality

      • typeConstraintList

        @Deprecated
public java.util.List typeConstraintList()
        Deprecated.
        Use typeConstraints().
        Return the type constraints of this variable. The constraints include the ones explicitly set to this variable, plus the constraint that the type of this variable must be no less than its current type, if it has one. The constraints are a list of inequalities.
        Returns:
        a list of Inequality objects.
        See Also:
        Inequality

      • _checkContainer

        protected void _checkContainer​(Entity container)
                        throws IllegalActionException
        Override the base class to ensure that the proposed container implements the TypedActor interface (the base class ensures that the container implements the Actor interface), is null, or is an EntityLibrary.
        Overrides:
        _checkContainer in class IOPort
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the proposed container is not a TypedActor, or if the base class throws it.

      • _checkTypedIOPortContainer

        protected final void _checkTypedIOPortContainer​(Entity container)
                                         throws IllegalActionException
        Override the base class to ensure that the proposed container implements the TypedActor interface (the base class ensures that the container implements the Actor interface), is null, or is an EntityLibrary. Derived classes may call this method to get the appropriate functionality if parent classes have redefined _checkContainer();
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the proposed container is not a TypedActor, or if the base class throws it.

      • _checkLiberalLink

        protected void _checkLiberalLink​(ComponentRelation relation)
                          throws IllegalActionException
        Override the method in the super class to ensure compatibility of the relation. This method is not synchronized on the workspace, so the caller should be.
        Parameters:
        relation - The relation to link to on the inside.
        Throws:
        IllegalActionException - If this port has no container or the relation is not an TypedIORelation, or the port already linked to a relation and is not a multiport, or the relation has width not exactly one and the port is not a multiport, or the relation is incompatible with this port, or the port is not in the same workspace as the relation.

      • _checkLink

        protected void _checkLink​(Relation relation)
                   throws IllegalActionException
        Override the method in the super class to ensure compatibility of the relation. This method is not synchronized on the workspace, so the caller should be.
        Overrides:
        _checkLink in class IOPort
        Parameters:
        relation - The relation to link to.
        Throws:
        IllegalActionException - If this port has no container or the relation is not an TypedIORelation, or the port already linked to a relation and is not a multiport, or if the relation has width not exactly one and the port is not a multiport, or the port is not in the same workspace as the relation.

      • _checkType

        protected void _checkType​(Token token)
                   throws IllegalActionException
        Check that the specified token as well as the token in the default value, if specified, is compatible with the resolved type of this port. If the resolved type is UNKNOWN then we have to assume unknown is acceptable (e.g. the port is not connected to anything), so we accept any token type. If the type is GENERAL, then we don't check the type because all types are lower and none are incomparable to GENERAL.
        Parameters:
        token - The token to check.
        Throws:
        IllegalActionException - If the specified token is either incomparable to the resolved type or higher in the type lattice.

      • _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 and in this 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 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.

        If the detail argument sets the bit defined by the constant TYPE, then append to the description a field of the form "type {declared declaredType resolved resolvedType}". The declared type is the type set through setTypeEquals(). If this method is not called, the declared type is BaseType.UNKNOWN. The resolved type is the type of this port. Both types are represented by the names of the corresponding tokens.

        This method is read-synchronized on the workspace.

        Overrides:
        _description in class IOPort
        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.