ptolemy.actor.lib
Class Subscriber

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Subscriber

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

SubscriptionAggregator

public class Subscriber
extends TypedAtomicActor

This actor subscribes to tokens on a named channel. The tokens are "tunneled" from an instance of Publisher that names the same channel and that is under the control of the same director. That is, it can be at a different level of the hierarchy, or in an entirely different composite actor, as long as the relevant composite actors are transparent (have no director).

Any number of instances of Subscriber can subscribe to the same channel.

This actor actually has a hidden input port that is connected to the publisher via hidden "liberal links" (links that are allowed to cross levels of the hierarchy). Consequently, any data dependencies that the director might assume on a regular "wired" connection will also be assumed across Publisher-Subscriber pairs. Similarly, type constraints will propagate across Publisher-Subscriber pairs. That is, the type of the Subscriber output will match the type of the Publisher input.

Since:

Ptolemy II 5.2

Version:

$Id: Subscriber.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee, Raymond A. Cardillo, Bert Rodiers

See Also:

Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Green (cxh)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

protected java.lang.String	_channel Cached channel name.
StringParameter	channel The name of the channel.
TypedIOPort	input The input port.
TypedIOPort	output The output port.

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

Subscriber(CompositeEntity container, java.lang.String name)
Construct a subscriber with the specified container and name.

Method Summary

protected void	_updateLinks() Update the connection to the publisher, if there is one.
void	attributeChanged(Attribute attribute) If the attribute is the channel, increment the workspace version to force cached receiver lists to be updated, and invalidate the schedule and resolved types of the director, if there is one.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Read at most one input token from each input channel and send it to the output.
void	preinitialize() Override the base class to ensure that there is a publisher.
void	setContainer(CompositeEntity container) If the new container is null, delete the named channel.

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, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, 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, 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

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

channel

public StringParameter channel

The name of the channel. Subscribers that reference this same channel will receive any transmissions to this port. This is a string that defaults to "channel1".

input

public TypedIOPort input

The input port. This base class imposes no type constraints except that the type of the input cannot be greater than the type of the output.

output

public TypedIOPort output

The output port. By default, the type of this output is constrained to be at least that of the input. This port is hidden by default and the actor handles creating connections to it.

_channel

protected java.lang.String _channel

Cached channel name.

Constructor Detail

Subscriber

public Subscriber(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException

Construct a subscriber with the specified container and name.

Parameters:

container - The container actor.

name - The name of the actor.

Throws:

IllegalActionException - If the actor is not of an acceptable class for the container.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is the channel, increment the workspace version to force cached receiver lists to be updated, and invalidate the schedule and resolved types of the director, if there is one.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace. This calls the base class and then set the filename public member.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Read at most one input token from each input channel and send it to the output.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director, or if there is no input connection.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Override the base class to ensure that there is a publisher.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If there is no matching publisher.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

If the new container is null, delete the named channel.

Overrides:

setContainer in class AtomicActor

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace.

NameDuplicationException - If the container already has an entity with the name of this entity.

See Also:

ComponentEntity.getContainer()

_updateLinks

protected void _updateLinks()
                     throws IllegalActionException

Update the connection to the publisher, if there is one. Note that this method is computationally intensive for large models as it traverses the model by searching up the hierarchy for the nearest opaque container or the top level and then traverses the contained entities. Thus, avoid calling this method except when the model is running.

Throws:

IllegalActionException - If creating the link triggers an exception.