ptolemy.actor.gui
Class Configuration

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.actor.gui.Configuration

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, ApplicationConfigurer, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

SingleWindowConfiguration

public class Configuration
extends CompositeEntity
implements ApplicationConfigurer

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.

To access the configuration from a random place, if you have a NamedObj foo, then you can call:

 Effigy effigy = Configuration.findEffigy(foo.toplevel());
 Configuration configuration = effigy.toplevel();
 

Since:

Ptolemy II 1.0

Version:

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

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/interfaces inherited from class ptolemy.kernel.CompositeEntity

CompositeEntity.ContainedObjectsIterator

Field Summary

private static java.util.List	_configurations The list of configurations that have been created.
static java.lang.String	_DIRECTORY_NAME The name of the model directory.
Parameter	classesToRemove A Parameter that is an array of Strings where each element names a class to be removed.
Parameter	removeGraphicalClasses A Parameter that if set to true adds RemoveGraphicalClasses to the list of MoMLFilters.

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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

private java.lang.String	_checkCloneFields(NamedObj namedObj) Check that clone(Workspace) method properly sets the fields.
private java.lang.String	_effigyIdentifier(Effigy effigy, NamedObj entity) Return an identifier for the specified effigy based on its container (if any) and its name.
private PtolemyEffigy	_findEffigyForModel(CompositeEntity composite, NamedObj model)
private Tableau	_openModel(NamedObj entity, CompositeEntity container) Open the specified model without deferring to its class definition.
protected void	_removeEntity(ComponentEntity entity) Remove the specified entity; if that entity is the model directory, then exit the application.
private void	_showTableaux(CompositeEntity container)
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.String	check() Check the configuration for common style problems.
static void	closeAllTableaux() Close all the tableaux.
static java.util.List	configurations() Return a list of all the configurations that have been created.
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	openInstance(NamedObj entity) Open the specified instance.
Tableau	openInstance(NamedObj entity, CompositeEntity container) Open the specified instance.
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(CompositeEntity 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, _deepOpaqueEntityList, _description, _exportMoMLContents, _finishedAddEntity, _recordDecoratedAttributes, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, clone, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, isOpaque, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, newRelation, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

_addPort, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, 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, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, 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.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

Field Detail

classesToRemove

public Parameter classesToRemove

A Parameter that is an array of Strings where each element names a class to be removed. The initial default value is an array with an empty element.

Kepler uses this parameter to remove certain classes:

  <property name="_classesToRemove" class="ptolemy.data.expr.Parameter"
  value="{"ptolemy.codegen.kernel.StaticSchedulingCodeGenerator","ptolemy.codegen.c.kernel.CCodeGenerator"}">
      <doc>An array of Strings, where each element names a class
  to removed by the MoMLFilter.</doc>
   >/property>
  

removeGraphicalClasses

public Parameter removeGraphicalClasses

A Parameter that if set to true adds RemoveGraphicalClasses to the list of MoMLFilters. Use this to run non-graphical classes. Note that setting this parameter and using MoMLApplication is not likely to work as MoMLApplication sets the look and feel which invokes the graphical system. The initial value is a boolean with the value false, indicating that RemoveGraphicalClasses should not be added to the filter list.

_DIRECTORY_NAME

public static final java.lang.String _DIRECTORY_NAME

The name of the model directory.

See Also:

Constant Field Values

_configurations

private static java.util.List _configurations

The list of configurations that have been created.

Constructor Detail

Configuration

public Configuration(Workspace workspace)
              throws IllegalActionException,
                     NameDuplicationException

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.

Throws:

IllegalActionException - If the container is incompatible with this entity.

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

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

check

public java.lang.String check()
                       throws java.lang.Exception

Check the configuration for common style problems.

Returns:

HTML describing the problems

Throws:

java.lang.Exception - If there is a problem cloning the configuration.

closeAllTableaux

public static void closeAllTableaux()
                             throws IllegalActionException

Close all the tableaux.

Throws:

IllegalActionException - If thrown while accessing the Configuration or while closing the tableaux.

configurations

public static java.util.List configurations()

Return a list of all the configurations that have been created. Note that if this method is called before a configuration is created, then it will return an empty linked list.

Returns:

A list of configurations, where each element of the list is of type Configuration.

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.

Parameters:

model - The Ptolemy model.

Returns:

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

openInstance

public Tableau openInstance(NamedObj entity)
                     throws IllegalActionException,
                            NameDuplicationException

Open the specified instance. If the instance 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 entity to open.

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).

openInstance

public Tableau openInstance(NamedObj entity,
                            CompositeEntity container)
                     throws IllegalActionException,
                            NameDuplicationException

Open the specified instance. If the instance 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).

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(CompositeEntity 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.

Overrides:

setContainer in class CompositeEntity

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the argument is not null.

See Also:

ComponentEntity.getContainer()

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.

_checkCloneFields

private java.lang.String _checkCloneFields(NamedObj namedObj)
                                    throws java.lang.CloneNotSupportedException,
                                           java.lang.IllegalAccessException,
                                           java.lang.ClassNotFoundException

Check that clone(Workspace) method properly sets the fields. In a cloned Director, Attribute or Actor, all private fields should either point to null or to distinct objects.

Parameters:

namedObj - The NamedObj, usually a Director, Attribute or actor to be checked.

Returns:

A string containing an error message if there is a problem, otherwise return the empty string.

Throws:

java.lang.CloneNotSupportedException - If namedObj does not support clone(Workspace).

java.lang.IllegalAccessException - If there is a problem getting a field.

java.lang.ClassNotFoundException - If a class cannot be found.

_effigyIdentifier

private java.lang.String _effigyIdentifier(Effigy effigy,
                                           NamedObj entity)

Return an identifier for the specified effigy based on its container (if any) and its name.

Returns:

An identifier for the effigy.

_findEffigyForModel

private PtolemyEffigy _findEffigyForModel(CompositeEntity composite,
                                          NamedObj model)

_openModel

private Tableau _openModel(NamedObj entity,
                           CompositeEntity container)
                    throws IllegalActionException,
                           NameDuplicationException

Open the specified model without deferring to its class definition.

Parameters:

entity - The model to open.

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).

_showTableaux

private void _showTableaux(CompositeEntity container)