ptolemy.actor.gui
Class Configuration

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.kernel.CompositeEntity
                      extended byptolemy.actor.gui.Configuration
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
SingleWindowConfiguration

public class Configuration
extends CompositeEntity

This is a base class for a composite entity that defines the configuration of an application that uses Ptolemy II classes. An instance of this class is in charge of the user interface, and coordinates multiple views of multiple models. One of its functions, for example, is to manage the opening of new models, ensuring that an appropriate view is used. It also makes sure that if a model is opened that is already open, then existing views are shown rather than creating new views.

The applications vergil and moml (at least) use configurations defined in MoML files, typically located in ptII/ptolemy/configs. The moml application takes as command line arguments a list of MoML files, the first of which is expected to define an instance of Configuration and its contents. That configuration is then used to open subsequent MoML files on the command line, and to manage the user interface.

Rather than performing all these functions itself, this class is a container for a model directory, effigy factories, and tableau factories that actually realize these functions. An application is configured by populating an instance of this class with a suitable set of these other classes. A minimal configuration defined in MoML is shown below:

   <?xml version="1.0" standalone="no"?>
   <!DOCTYPE entity PUBLIC "-//UC Berkeley//DTD MoML 1//EN"
   "http://ptolemy.eecs.berkeley.edu/xml/dtd/MoML_1.dtd">
   <entity name="configuration" class="ptolemy.actor.gui.Configuration">
   <doc>Configuration to run but not edit Ptolemy II models</doc>
   <entity name="directory" class="ptolemy.actor.gui.ModelDirectory"/>
   <entity name="effigyFactory" class="ptolemy.actor.gui.PtolemyEffigy$Factory"/>
   <property name="tableauFactory" class="ptolemy.actor.gui.RunTableau$Factory"/>
   </entity>
   

It must contain, at a minimum, an instance of ModelDirectory, named "directory", and an instance of EffigyFactory, named "effigyFactory". The openModel() method delegates to the effigy factory the opening of a model. It may also contain an instance of TextEditorTableauFactory, named "tableauFactory". A tableau is a visual representation of the model in a top-level window. The above minimal configuration can be used to run Ptolemy II models by opening a run panel only.

When the directory becomes empty (all models have been closed), it removes itself from the configuration. When this happens, the configuration calls System.exit() to exit the application.

Since:
Ptolemy II 1.0
Version:
$Id: Configuration.java,v 1.75.2.1 2004/06/18 00:48:50 cxh Exp $
Author:
Steve Neuendorffer and Edward A. Lee
See Also:
EffigyFactory, ModelDirectory, Tableau, TextEditorTableau, Serialized Form
Accepted Rating:
Yellow (celaine)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.CompositeEntity
CompositeEntity.ContainedObjectsIterator
 
Field Summary
static java.lang.String _DIRECTORY_NAME
          The name of the model directory.
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Constructor Summary
Configuration(Workspace workspace)
          Construct an instance in the specified workspace with an empty string as a name.
 
Method Summary
protected  void _removeEntity(ComponentEntity entity)
          Remove the specified entity; if that entity is the model directory, then exit the application.
 Tableau createPrimaryTableau(Effigy effigy)
          Create the first tableau for the given effigy, using the tableau factory.
static Effigy findEffigy(NamedObj model)
          Find an effigy for the specified model by searching all the configurations that have been created.
 ModelDirectory getDirectory()
          Get the model directory.
 PtolemyEffigy getEffigy(NamedObj model)
          Get the effigy for the specified Ptolemy model.
 Tableau openModel(NamedObj entity)
          Open the specified Ptolemy II model.
 Tableau openModel(NamedObj entity, CompositeEntity container)
          Open the specified Ptolemy II model.
 Tableau openModel(java.net.URL base, java.net.URL in, java.lang.String identifier)
          Open the specified URL.
 Tableau openModel(java.net.URL base, java.net.URL in, java.lang.String identifier, EffigyFactory factory)
          Open the specified URL using the specified effigy factory.
 void setContainer(InstantiableNamedObj container)
          If the argument is not null, then throw an exception.
 void showAll()
          Find all instances of Tableau deeply contained in the directory and call show() on them.
 
Methods inherited from class ptolemy.kernel.CompositeEntity
_addEntity, _addRelation, _adjustDeferrals, _description, _exportMoMLContents, _finishedAddEntity, _removeRelation, allAtomicEntityList, allowLevelCrossingConnect, classDefinitionList, clone, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, entityList, entityList, exportLinks, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, isOpaque, newRelation, numberOfClassDefinitions, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_addPort, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, newPort, propagateExistence, setContainer, setName
 
Methods inherited from class ptolemy.kernel.Entity
_removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition
 
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, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, 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.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

_DIRECTORY_NAME

public static final java.lang.String _DIRECTORY_NAME
The name of the model directory.

See Also:
Constant Field Values
Constructor Detail

Configuration

public Configuration(Workspace workspace)
Construct an instance in the specified workspace with an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the instance to the workspace directory. Increment the version number of the workspace. Note that there is no constructor that takes a container as an argument; a Configuration is always a top-level entity (this is enforced by the setContainer() method).

Parameters:
workspace - The workspace that will list the entity.
Method Detail

createPrimaryTableau

public Tableau createPrimaryTableau(Effigy effigy)
Create the first tableau for the given effigy, using the tableau factory. This is called after an effigy is first opened, or when a new effigy is created. If the method fails to create a tableau, then it removes the effigy from the directory. This prevents us from having lingering effigies that have no user interface.

Parameters:
effigy - The effigy for which to create a tableau.
Returns:
A tableau for the specified effigy, or null if none can be opened.

findEffigy

public static Effigy findEffigy(NamedObj model)
Find an effigy for the specified model by searching all the configurations that have been created. Although typically there is only one, in principle there may be more than one. This can be used to find a configuration, which is typically the result of calling toplevel() on the effigy.

Parameters:
model - The model for which to find an effigy.
Returns:
An effigy, or null if none can be found.

getDirectory

public ModelDirectory getDirectory()
Get the model directory.

Returns:
The model directory, or null if there isn't one.

getEffigy

public PtolemyEffigy getEffigy(NamedObj model)
Get the effigy for the specified Ptolemy model. This searches all instances of PtolemyEffigy deeply contained by the directory, and returns the first one it encounters that is an effigy for the specified model.

Returns:
The effigy for the model, or null if none is found.

openModel

public Tableau openModel(java.net.URL base,
                         java.net.URL in,
                         java.lang.String identifier)
                  throws java.lang.Exception
Open the specified URL. If a model with the specified identifier is present in the directory, then find all the tableaux of that model and make them visible; otherwise, read a model from the specified URL in and create a default tableau for the model and add the tableau to this directory.

Parameters:
base - The base for relative file references, or null if there are no relative file references.
in - The input URL.
identifier - The identifier that uniquely identifies the model.
Returns:
The tableau that is created, or null if none.
Throws:
java.lang.Exception - If the URL cannot be read.

openModel

public Tableau openModel(java.net.URL base,
                         java.net.URL in,
                         java.lang.String identifier,
                         EffigyFactory factory)
                  throws java.lang.Exception
Open the specified URL using the specified effigy factory. If a model with the specified identifier is present in the directory, then find all the tableaux of that model and make them visible; otherwise, read a model from the specified URL in and create a default tableau for the model and add the tableau to this directory.

Parameters:
base - The base for relative file references, or null if there are no relative file references.
in - The input URL.
identifier - The identifier that uniquely identifies the model.
factory - The effigy factory to use.
Returns:
The tableau that is created, or null if none.
Throws:
java.lang.Exception - If the URL cannot be read.

openModel

public Tableau openModel(NamedObj entity)
                  throws IllegalActionException,
                         NameDuplicationException
Open the specified Ptolemy II model. If a model already has open tableaux, then put those in the foreground and return the first one. Otherwise, create a new tableau and if necessary, a new effigy. Unless there is a more natural container for the effigy (e.g. it is a hierarchical model), then if a new effigy is created, it is put into the directory of the configuration. Any new tableau created will be contained by that effigy.

Parameters:
entity - The model.
Returns:
The tableau that is created, or the first one found, or null if none is created or found.
Throws:
IllegalActionException - If constructing an effigy or tableau fails.
NameDuplicationException - If a name conflict occurs (this should not be thrown).

openModel

public Tableau openModel(NamedObj entity,
                         CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException
Open the specified Ptolemy II model. If a model already has open tableaux, then put those in the foreground and return the first one. Otherwise, create a new tableau and, if necessary, a new effigy. Unless there is a more natural place for the effigy (e.g. it is a hierarchical model), then if a new effigy is created, it is put into the container argument, or if that is null, into the directory of the configuration. Any new tableau created will be contained by that effigy.

Parameters:
entity - The model.
container - The container for any new effigy.
Returns:
The tableau that is created, or the first one found, or null if none is created or found.
Throws:
IllegalActionException - If constructing an effigy or tableau fails.
NameDuplicationException - If a name conflict occurs (this should not be thrown).

setContainer

public void setContainer(InstantiableNamedObj container)
                  throws IllegalActionException
If the argument is not null, then throw an exception. This ensures that the object is always at the top level of a hierarchy.

Parameters:
container - The proposed container.
Throws:
IllegalActionException - If the argument is not null.

showAll

public void showAll()
Find all instances of Tableau deeply contained in the directory and call show() on them. If there is no directory, then do nothing.


_removeEntity

protected void _removeEntity(ComponentEntity entity)
Remove the specified entity; if that entity is the model directory, then exit the application. This method should not be called directly. Call the setContainer() method of the entity instead with a null argument. The entity is assumed to be contained by this composite (otherwise, nothing happens). This does not alter the entity in any way. This method is not synchronized on the workspace, so the caller should be.

Overrides:
_removeEntity in class CompositeEntity
Parameters:
entity - The entity to remove.