ptolemy.domains.wireless.kernel
Class AtomicWirelessChannel

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.domains.wireless.kernel.AtomicWirelessChannel
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, PropertyTransformer, java.io.Serializable, TypedActor, ValueListener, WirelessChannel
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.

Since:
Ptolemy II 4.0
Version:
$Id: AtomicWirelessChannel.java,v 1.23.2.1 2004/06/20 03:10:46 cxh Exp $
Author:
Xiaojun Liu, Edward A. Lee and Yang Zhao
See Also:
Serialized Form
Accepted Rating:
Yellow (cxh)
Proposed Rating:
Green (cxh)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
protected  boolean _receiversInRangeCacheValid
          Flag indicating that the cached list of receivers in range is valid.
 Parameter defaultProperties
          The default properties for transmission.
 
Fields inherited from class ptolemy.actor.AtomicActor
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
AtomicWirelessChannel(CompositeEntity container, java.lang.String name)
          Construct a relation with the given name contained by the specified entity.
 
Method Summary
protected  double _distanceBetween(WirelessIOPort port1, WirelessIOPort port2)
          Return the distance between two ports.
protected  boolean _isInRange(WirelessIOPort source, WirelessIOPort destination, RecordToken properties)
          Return true if the specified destination port is in range of the specified source port, assuming the source port transmits with the specified properties.
protected  double[] _locationOf(IOPort port)
          Return the location of the given port.
protected  java.util.List _receiversInRange(WirelessIOPort sourcePort, RecordToken properties)
          Return the list of receivers that can receive from the specified port with the specified transmission properties.
protected  void _transmitTo(Token token, WirelessIOPort sender, WirelessReceiver receiver, RecordToken properties)
          Transmit the specified token to the specified receiver.
 void attributeChanged(Attribute attribute)
          If the attribute is defaultProperties, make sure its value is a record token.
 ChannelPort getChannelPort()
          Return a channel port that can be used to set type constraints between senders and receivers.
 java.util.List listeningInputPorts()
          Return a list of input ports that can potentially receive data from this channel.
 java.util.List listeningOutputPorts()
          Return a list of output ports that can potentially receive data from this channel.
 void pruneDependencies()
          Override the base class to declare that the dummy port returned by getChannelPort() does not depend on itself in a firing.
 void registerPropertyTransformer(PropertyTransformer transformer, WirelessIOPort port)
          Register a property transformer for transmissions from the specified port.
 java.util.List sendingInputPorts()
          Return a list of input ports that can potentially send data to this channel.
 java.util.List sendingOutputPorts()
          Return a list of output ports that can potentially send data to this channel.
 RecordToken transformProperties(RecordToken properties, WirelessIOPort source, WirelessIOPort destination)
          Transform the transmission property to take into account channel losses, noise, etc., for transmission between the specified source and the specified destination.
 void transmit(Token token, WirelessIOPort port, RecordToken properties)
          Transmit the specified token from the specified port with the specified properties.
 void unregisterPropertyTransformer(PropertyTransformer transformer, WirelessIOPort port)
          Unregister a property transformer for transmissions from the specified port (or from null for a generic property transformer).
 void valueChanged(Settable settable)
          React to changes of the specified Settable.
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, removeDependency, setContainer, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
fire, initialize, iterate, postfire, prefire, preinitialize, stop, stopFire, terminate, wrapup
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getContainer, getFullName, getName, getName, setName
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 

Field Detail

defaultProperties

public Parameter defaultProperties
The default properties for transmission. In this base class, the type and contents are left undefined. Derived classes will define this to be a record. The fields of the record determine what properties are seen by the receiver. Any fields that are not in this parameter value will be discarded before properties are delivered to the receiver. FIXME: need a mechanism to deal with empty record tokens.


_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

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException
If the attribute is defaultProperties, make sure its value is a record token.

Overrides:
attributeChanged in class NamedObj
Parameters:
attribute - The attribute that changed.
Throws:
IllegalActionException - If the change is not acceptable to this container.

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.

pruneDependencies

public void pruneDependencies()
Override the base class to declare that the dummy port returned by getChannelPort() does not depend on itself in a firing. This port is both an input and an output, so by default there would be a self dependency.

Overrides:
pruneDependencies in class AtomicActor
See Also:
TimedDelay, AtomicActor.removeDependency(IOPort, IOPort), FunctionDependencyOfAtomicActor

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.

unregisterPropertyTransformer

public void unregisterPropertyTransformer(PropertyTransformer transformer,
                                          WirelessIOPort port)
Unregister a property transformer for transmissions from the specified port (or from null for a generic property transformer). If the transformer has not been registered, then do nothing.

Specified by:
unregisterPropertyTransformer in interface WirelessChannel
Parameters:
transformer - The property transformer to be unregistered.
port - The port whose transmissions should be subject to the property transformer, or null for a generic transformer.
See Also:
registerPropertyTransformer(PropertyTransformer, WirelessIOPort)

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.