ptolemy.vergil.actor.lib
Class VisualModelReference

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.hoc.ModelReference
                              ptolemy.vergil.actor.lib.VisualModelReference

All Implemented Interfaces:

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

public class VisualModelReference
extends ModelReference

This is an atomic actor that can execute and/or open a model specified by a file or URL. This can be used to define an actor whose firing behavior is given by a complete execution of another model. It extends the base class with the following attributes and associated capabilities.

• openOnFiring: The value of this string attribute determines what open happens when the fire() method is invoked. The recognized values are:
  • "do not open" (the default)
  • "open in Vergil"
  • "open in Vergil (full screen)"
  Note that it is dangerous to use the full-screen mode because it becomes difficult to stop execution of the model that contains this actor. In full-screen mode, the referenced model will consume the entire screen. Stopping that execution will only serve to stop the current iteration, and very likely, another iteration will begin immediately and again occupy the entire screen. Use this option with care.
• closeOnPostfire: The value of this string attribute determines what happens in the postfire() method. The recognized values are:
  • "do nothing" (the default)
  • "close Vergil graph"

Since:

Ptolemy II 4.0

Version:

$Id: VisualModelReference.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee, Elaine Cheong

See Also:

Variable, Parameter, Settable, Serialized Form

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

class

VisualModelReference.LookInside A tableau factory to override the look inside behavior to open the referenced model, if there is one.

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

Entity.ContainedObjectsIterator

Field Summary

private static int	_CLOSE_VERGIL_GRAPH
private int	_closeOnPostfireValue The value of the closeOnPostfire parameter.
private static int	_DO_NOT_OPEN
private static int	_DO_NOTHING
private PtolemyEffigy	_effigy Effigy that has been created (if any).
private java.lang.Exception	_exception Store exception thrown in event thread.
private static int	_OPEN_IN_VERGIL
private static int	_OPEN_IN_VERGIL_FULL_SCREEN
private int	_openOnFiringValue The value of the openOnFiring parameter.
private Tableau	_tableau Tableau that has been created (if any).
StringParameter	closeOnPostfire The value of this string parameter determines what close action happens in the postfire() method.
StringParameter	openOnFiring The value of this string parameter determines what open happens when the fire() method is invoked.

Fields inherited from class ptolemy.actor.lib.hoc.ModelReference

_alreadyReadInputs, _model, executionOnFiring, lingerTime, modelFileOrURL, postfireAction

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

VisualModelReference(CompositeEntity container, java.lang.String name)
Construct a VisualModelReference with a name and a container.

Method Summary

void	attributeChanged(Attribute attribute) Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.
java.lang.Object	clone(Workspace workspace) Clone this actor into the specified workspace.
void	fire() Run a complete execution of the referenced model.
boolean	postfire() Override the base class to perform requested close on postfire actions.

Methods inherited from class ptolemy.actor.lib.hoc.ModelReference

_readInputsAndValidateSettables, executionError, executionFinished, managerStateChanged, stop, stopFire, terminate, wrapup

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, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer

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, prefire

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, removeInitializable

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

openOnFiring

public StringParameter openOnFiring

The value of this string parameter determines what open happens when the fire() method is invoked. The recognized values are:

• "do not open" (the default)
• "open in Vergil"
• "open in Vergil (full screen)"

closeOnPostfire

public StringParameter closeOnPostfire

The value of this string parameter determines what close action happens in the postfire() method. The recognized values are:

• "do nothing" (the default)
• "close Vergil graph"

_DO_NOT_OPEN

private static int _DO_NOT_OPEN

_OPEN_IN_VERGIL

private static int _OPEN_IN_VERGIL

_OPEN_IN_VERGIL_FULL_SCREEN

private static int _OPEN_IN_VERGIL_FULL_SCREEN

_openOnFiringValue

private transient int _openOnFiringValue

The value of the openOnFiring parameter.

_DO_NOTHING

private static int _DO_NOTHING

_CLOSE_VERGIL_GRAPH

private static int _CLOSE_VERGIL_GRAPH

_closeOnPostfireValue

private transient int _closeOnPostfireValue

The value of the closeOnPostfire parameter.

_exception

private java.lang.Exception _exception

Store exception thrown in event thread.

_tableau

private Tableau _tableau

Tableau that has been created (if any).

_effigy

private PtolemyEffigy _effigy

Effigy that has been created (if any).

Constructor Detail

VisualModelReference

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

Construct a VisualModelReference with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This actor 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. Increment the version of the workspace. This actor will have no local director initially, and its executive director will be simply the director of the container.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.

Overrides:

attributeChanged in class ModelReference

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

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

Clone this actor into the specified workspace. Override the base class to ensure that private variables are reset to null.

Overrides:

clone in class ModelReference

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new instance of VisualModelReference.

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

Run a complete execution of the referenced model. A complete execution consists of invocation of super.initialize(), repeated invocations of super.prefire(), super.fire(), and super.postfire(), followed by super.wrapup(). The invocations of prefire(), fire(), and postfire() are repeated until either the model indicates it is not ready to execute (prefire() returns false), or it requests a stop (postfire() returns false or stop() is called). Before running the complete execution, this method examines input ports, and if they are connected, have data, and if the referenced model has a top-level parameter with the same name, then one token is read from the input port and used to set the value of the parameter in the referenced model. After running the complete execution, if there are any output ports, then this method looks for top-level parameters in the referenced model with the same name as the output ports, and if there are any, reads their values and produces them on the output. If no model has been specified, then this method does nothing.

Specified by:

fire in interface Executable

Overrides:

fire in class ModelReference

Throws:

IllegalActionException - If there is no director, or if the director's action methods throw it.

postfire

public boolean postfire()
                 throws IllegalActionException

Override the base class to perform requested close on postfire actions. Note that if a close is requested, then this method waits until the AWT event thread completes the close. This creates the possibility of a deadlock.

Specified by:

postfire in interface Executable

Overrides:

postfire in class ModelReference

Returns:

Whatever the superclass returns (probably true).

Throws:

IllegalActionException - Thrown if a parent class throws it.