Package ptolemy.domains.wireless.kernel

Class AtomicWirelessChannel

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, ChannelListener, PropertyTransformer, WirelessChannel, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, ValueListener
    Direct Known Subclasses:
    ErasureChannel
    public class AtomicWirelessChannel
extends TypedAtomicActor
implements WirelessChannel, ValueListener
    The base class for communication channels in the wireless domain.

    To use this class, place it in a wireless model that contains a wireless director and wireless actors (actors whose ports are instances of WirelessIOPort). Then set the outsideChannel parameter of those ports to match the name of this channel. The model can also itself contain ports that are instances of WirelessIOPort, in which case their insideChannel parameter should contain the name of this channel if they should use this channel.

    In this base class, transmission on a channel reaches all ports at the same level of the hierarchy that are instances of WirelessIOPort and that specify that they use this channel. These ports include those contained by entities that have the container as this channel and that have their outsideChannel parameter set to the name of this channel. They also include those ports whose containers are the same as the container of this channel and whose insideChannel parameter matches this channel name.

    Derived classes will typically limit the range of the transmission, using for example location information from the ports. They may also introduce random losses or corruption of data. To do this, derived classes can override the _isInRange() protected method, or the transmit() public method.

    Other classes may register a property transformer that allows them to modify meta data prior to transmission of the data token on the channel.

    Since:
    Ptolemy II 4.0
    Version:
    $Id$
    Author:
    Xiaojun Liu, Edward A. Lee, Yang Zhao, Heather Taylor, Elaine Cheong
    Pt.AcceptedRating:
    Yellow (cxh)
    Pt.ProposedRating:
    Green (cxh)

    • Field Detail

      • defaultProperties

        public Parameter defaultProperties
        The default properties for transmission. In this base class, the type is constrained to be a record and the default value is set to an empty record. Derived classes will define this to be a record.

      • name

        public NameParameter name
        When set to a non-empty value, this NameParameter will cause the name of this channel to be set to this value.

      • _receiversInRangeCacheValid

        protected boolean _receiversInRangeCacheValid
        Flag indicating that the cached list of receivers in range is valid. This gets set to false whenever a location for some object whose location has been obtained by _locationOf() has changed since the last time this cached list was constructed. In addition, subclasses may invalidate this if anything else that affects whether a receiver is in range changes (such as the transmit properties of a port).

    • Constructor Detail

      • AtomicWirelessChannel

        public AtomicWirelessChannel​(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

      • addChannelListener

        public void addChannelListener​(ChannelListener listener)
        Add a channel listener to listen for transmissions on this channel. A ChannelListener can read the transmission property and token that was transmitted on this channel. If the channel listener has already been added, then no changes are made. If multiple channel listeners are registered that can operate on a given transmission, then the order in which they are applied is arbitrary.
        Specified by:
        addChannelListener in interface WirelessChannel
        Parameters:
        listener - The channel listener to add.
        See Also:
        removeChannelListener(ChannelListener)

      • 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).
        Overrides:
        clone in class TypedAtomicActor
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new Attribute.
        Throws:
        java.lang.CloneNotSupportedException - Not thrown in this base class
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • getChannelPort

        public ChannelPort getChannelPort()
        Return a channel port that can be used to set type constraints between senders and receivers. An channel contains a single port, which is an instance of ChannelPort. The port is merely used to set up n type constrains instead of n*n, where n is the number of ports using the channel.
        Specified by:
        getChannelPort in interface WirelessChannel
        Returns:
        The channel port.

      • listeningInputPorts

        public java.util.List listeningInputPorts()
                                   throws IllegalActionException
        Return a list of input ports that can potentially receive data from this channel. This must include input ports contained by entities contained by the container of this channel that have their outsideChannel parameter set to the name of this channel. Transparent hierarchy is not supported.
        Specified by:
        listeningInputPorts in interface WirelessChannel
        Returns:
        The list of input ports of class WirelessIOPort using this channel.
        Throws:
        IllegalActionException - If a port is encountered whose outsideChannel parameter cannot be evaluated.

      • listeningOutputPorts

        public java.util.List listeningOutputPorts()
                                    throws IllegalActionException
        Return a list of output ports that can potentially receive data from this channel. This must include output ports contained by the container of this channel that have their insideChannel parameter set to the name of this channel. This method gets read access on the workspace.
        Specified by:
        listeningOutputPorts in interface WirelessChannel
        Returns:
        The list of output ports of class WirelessIOPort using this channel.
        Throws:
        IllegalActionException - If a port is encountered whose insideChannel parameter cannot be evaluated.

      • registerPropertyTransformer

        public void registerPropertyTransformer​(PropertyTransformer transformer,
                                        WirelessIOPort port)
        Register a property transformer for transmissions from the specified port. If null is given for the port, then the property transformer will be used for all transmissions through this channel. If the property transformer is already registered, then no changes are made.
        Specified by:
        registerPropertyTransformer in interface WirelessChannel
        Parameters:
        transformer - The property transformer to be registered.
        port - The port whose transmissions should be subject to the property transformer, or null to make them subject to all transmissions through this channel.

      • sendingInputPorts

        public java.util.List sendingInputPorts()
                                 throws IllegalActionException
        Return a list of input ports that can potentially send data to this channel. This must include input ports contained by the container of this channel that have their insideChannel parameter set to the name of this channel. This method gets read access on the workspace.
        Specified by:
        sendingInputPorts in interface WirelessChannel
        Returns:
        The list of input ports of class WirelessIOPort using this channel.
        Throws:
        IllegalActionException - If a port is encountered whose insideChannel parameter cannot be evaluated.

      • sendingOutputPorts

        public java.util.List sendingOutputPorts()
                                  throws IllegalActionException
        Return a list of output ports that can potentially send data to this channel. This must include output ports contained by entities contained by the container of this channel that have their outsideChannel parameter set to the name of this channel. This method gets read access on the workspace.
        Specified by:
        sendingOutputPorts in interface WirelessChannel
        Returns:
        The list of output ports of class WirelessIOPort using this channel.
        Throws:
        IllegalActionException - If a port is encountered whose outsideChannel parameter cannot be evaluated.

      • transformProperties

        public RecordToken transformProperties​(RecordToken properties,
                                       WirelessIOPort source,
                                       WirelessIOPort destination)
                                throws IllegalActionException
        Transform the transmission property to take into account channel losses, noise, etc., for transmission between the specified source and the specified destination. In this base class, the specified properties are merged with the defaultProperties so that the resulting properties contain at least all the fields of the defaultProperties. In addition, any property transformers that have been registered are applied.
        Specified by:
        transformProperties in interface PropertyTransformer
        Parameters:
        properties - The transmission properties.
        source - The sending port.
        destination - The receiving port.
        Returns:
        The transformed properties.
        Throws:
        IllegalActionException - If the properties cannot be transformed. Not thrown in this base class.
        See Also:
        registerPropertyTransformer(PropertyTransformer, WirelessIOPort)

      • transmit

        public void transmit​(Token token,
                     WirelessIOPort port,
                     RecordToken properties)
              throws IllegalActionException
        Transmit the specified token from the specified port with the specified properties. All ports that are in range will receive the token if they have room in their receiver. Note that in this base class, a port is in range if it refers to this channel by name and is at the right place in the hierarchy. This base class makes no use of the properties argument. But derived classes may limit the range or otherwise change transmission properties using this argument.
        Specified by:
        transmit in interface WirelessChannel
        Parameters:
        token - The token to transmit, or null to clear all receivers that are in range.
        port - The port from which this is being transmitted.
        properties - The transmission properties (ignored in this base class).
        Throws:
        IllegalActionException - If a type conflict occurs, or the director is not a WirelessDirector.

      • valueChanged

        public void valueChanged​(Settable settable)
        React to changes of the specified Settable. This base class registers as a listener to attributes that specify the location of objects (and implement the Locatable interface) so that it is notified by a call to this method when the location changes. In this base class, this method only sets a flag to invalidate its cached list of receivers in range. Subclass may do more, for example to determine whether a receiver that is in process of receiving a message with a non-zero duration is still in range.
        Specified by:
        valueChanged in interface ValueListener
        Parameters:
        settable - The object that has changed value.

      • _distanceBetween

        protected double _distanceBetween​(WirelessIOPort port1,
                                  WirelessIOPort port2)
                           throws IllegalActionException
        Return the distance between two ports. This is a convenience method provided to make it easier to write subclasses that limit transmission range using position information. In this base class. locations are specified in 2 dimensions. Subclass might overwrite this method to deal with 3 dimensions. FIXME: We may also want this method to be dimension independent.
        Parameters:
        port1 - The first port.
        port2 - The second port.
        Returns:
        The distance between the two ports.
        Throws:
        IllegalActionException - If the distance cannot be determined.

      • _isInRange

        protected boolean _isInRange​(WirelessIOPort source,
                             WirelessIOPort destination,
                             RecordToken properties)
                      throws IllegalActionException
        Return true if the specified destination port is in range of the specified source port, assuming the source port transmits with the specified properties. In this base class, this method returns true always. The method assumes that the two ports are communicating on the same channel, but it does not check this. This should be checked by the calling method. Derived classes will typically use position information in the source or destination to determine whether ports are in range.
        Parameters:
        source - The source port.
        destination - The destination port.
        properties - The transmission properties (ignored in this base class).
        Returns:
        True if the destination is in range of the source.
        Throws:
        IllegalActionException - If it cannot be determined whether the destination is in range (not thrown in this base class).

      • _locationOf

        protected double[] _locationOf​(IOPort port)
                        throws IllegalActionException
        Return the location of the given port. If the container of the specified port is the container of this channel, then use the "_location" attribute of the port. Otherwise, use the "_location" attribute of its container. In either case, register a listener to the location attribute so that valueChanged() will be called if and when that location changes. Note that transparent hierarchy is not supported in getting the location. The calling method is expected to have read access on the workspace. Subclasses may override this method to provide some other way of obtaining location information.
        Parameters:
        port - A port with a location.
        Returns:
        The location of the port.
        Throws:
        IllegalActionException - If a valid location attribute cannot be found.

      • _receiversInRange

        protected java.util.List _receiversInRange​(WirelessIOPort sourcePort,
                                           RecordToken properties)
                                    throws IllegalActionException
        Return the list of receivers that can receive from the specified port with the specified transmission properties. Ports that are contained by the same container as the specified sourcePort are not included. Note that this method does not guarantee that those receivers will receive. That is determined by the transmit() method, which subclasses may override to, for example, introduce probabilistic message losses. The calling method is expected to have read access on the workspace.
        Parameters:
        sourcePort - The sending port.
        properties - The transmission properties (ignored in this base class).
        Returns:
        A list of instances of WirelessReceiver.
        Throws:
        IllegalActionException - If a location of a port cannot be evaluated.

      • _transmitTo

        protected void _transmitTo​(Token token,
                           WirelessIOPort sender,
                           WirelessReceiver receiver,
                           RecordToken properties)
                    throws IllegalActionException
        Transmit the specified token to the specified receiver. If necessary, the token will be converted to the resolved type of the port containing the specified receiver.
        Parameters:
        token - The token to transmit, or null to clear the specified receiver.
        sender - The sending port.
        receiver - The receiver to which to transmit.
        properties - The transmission properties (ignored in this base class).
        Throws:
        IllegalActionException - If the token cannot be converted or if the token argument is null and the destination receiver does not support clear.