ptolemy.domains.wireless.kernel
Class AtomicWirelessChannel

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.wireless.kernel.AtomicWirelessChannel

All Implemented Interfaces:

java.io.Serializable, 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: AtomicWirelessChannel.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Xiaojun Liu, Edward A. Lee, Yang Zhao, Heather Taylor, Elaine Cheong

See Also:

Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Green (cxh)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private java.util.Set	_channelListeners The channel listeners that have been added.
private ChannelPort	_channelPort Dummy port used to reduce the type constraints to 2N rather than N^2.
private java.util.List	_listeningInputPorts
private long	_listeningInputPortsVersion
private java.util.List	_listeningOutputPorts
private long	_listeningOutputPortsVersion
private java.util.Set	_propertyTransformers The property transformers that have been registered without specifying a port.
private java.util.HashMap	_propertyTransformersByPort The property transformers that have been registered to operate on transmissions from a particular port, indexed by port.
private java.util.HashMap	_receiversInRangeCache
protected boolean	_receiversInRangeCacheValid Flag indicating that the cached list of receivers in range is valid.
private java.util.HashMap	_receiversInRangeCacheVersion
private java.util.List	_sendingInputPorts
private long	_sendingInputPortsVersion
private java.util.List	_sendingOutputPorts
private long	_sendingOutputPortsVersion
Parameter	defaultProperties The default properties for transmission.
private static java.lang.String	LOCATION_ATTRIBUTE_NAME
NameParameter	name When set to a non-empty value, this NameParameter will cause the name of this channel to be set to this value.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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	addChannelListener(ChannelListener listener) Add a channel listener to listen for transmissions on this channel.
void	channelNotify(RecordToken properties, Token token, WirelessIOPort source, WirelessIOPort destination) Notify any channel listeners that have been added.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
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	preinitialize() 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.
void	removeChannelListener(ChannelListener listener) Remove a channel listener for transmissions on this channel.
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, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, 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 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).

_listeningInputPorts

private java.util.List _listeningInputPorts

_listeningInputPortsVersion

private long _listeningInputPortsVersion

_listeningOutputPorts

private java.util.List _listeningOutputPorts

_listeningOutputPortsVersion

private long _listeningOutputPortsVersion

_propertyTransformers

private java.util.Set _propertyTransformers

The property transformers that have been registered without specifying a port.

_propertyTransformersByPort

private java.util.HashMap _propertyTransformersByPort

The property transformers that have been registered to operate on transmissions from a particular port, indexed by port.

_channelListeners

private java.util.Set _channelListeners

The channel listeners that have been added.

_receiversInRangeCache

private java.util.HashMap _receiversInRangeCache

_receiversInRangeCacheVersion

private java.util.HashMap _receiversInRangeCacheVersion

_sendingInputPorts

private java.util.List _sendingInputPorts

_sendingInputPortsVersion

private long _sendingInputPortsVersion

_sendingOutputPorts

private java.util.List _sendingOutputPorts

_sendingOutputPortsVersion

private long _sendingOutputPortsVersion

LOCATION_ATTRIBUTE_NAME

private static final java.lang.String LOCATION_ATTRIBUTE_NAME

See Also:

Constant Field Values

_channelPort

private ChannelPort _channelPort

Dummy port used to reduce the type constraints to 2N rather than N^2. This port is returned by instances of WirelessIOPort when asked for sink ports. Do not send data to this port, however. Instead, use the transmit() method.

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)

channelNotify

public void channelNotify(RecordToken properties,
                          Token token,
                          WirelessIOPort source,
                          WirelessIOPort destination)

Notify any channel listeners that have been added.

Specified by:

channelNotify in interface ChannelListener

Parameters:

properties - The transmission properties.

token - The token to be processed.

source - The sending port.

destination - The receiving port.

See Also:

addChannelListener(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 AtomicActor

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.

preinitialize

public void preinitialize()
                   throws IllegalActionException

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.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it.

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.

removeChannelListener

public void removeChannelListener(ChannelListener listener)

Remove a channel listener for transmissions on this channel. If the listener has not been added, then do nothing.

Specified by:

removeChannelListener in interface WirelessChannel

Parameters:

listener - The channel listener to remove.

See Also:

addChannelListener(ChannelListener)

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.