ptolemy.actor.gui
Class Effigy

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.Effigy
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
BrowserEffigy, ExpressionShellEffigy, HTMLEffigy, PlotEffigy, PtolemyEffigy, TextEffigy, TokenEffigy

public class Effigy
extends CompositeEntity

An effigy represents model metadata, and is contained by the model directory or by another effigy. The effigy, for example, keeps track of where the model originated (from a URI or file) and whether the model has been modified since the URI or file was read. In design automation, such information is often called "metadata." When we began to design this class, we called it ModelModel, because it was a model of a Ptolemy II model. However, this name seemed awkward, so we changed it to Effigy. We also considered the name Proxy for the class. We rejected that name because of the common use of the word "proxy" in distributed object-oriented models.

The Effigy class extends CompositeEntity, so an instance of Effigy can contain entities. By convention, an effigy contains all open instances of Tableau associated with the model. It also contains a string attribute named "identifier" with a value that uniquely identifies the model. A typical choice (which depends on the configuration) is the canonical URI for a MoML file that describes the model. In the case of an effigy contained by another, a typical choice is the URI of the parent effigy, a pound sign "#", and a name.

An effigy may contain other effigies. The top effigy in such a containment hierarchy is associated with a URI or file. Contained effigies are associated with the same file, and represent structured data within the top-level representation in the file. The topEffigy() method returns that top effigy.

NOTE: It might seem more natural for the identifier to match the name of the effigy rather than recording the identifier in a string attribute. But in Ptolemy II, an entity name cannot have periods in it, and a URI typically does have periods in it.

Since:
Ptolemy II 1.0
Version:
$Id: Effigy.java,v 1.54 2004/04/13 02:58:57 cxh Exp $
Author:
Steve Neuendorffer and Edward A. Lee
See Also:
ModelDirectory, Tableau, 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
 StringAttribute identifier
          The identifier for the effigy.
 URIAttribute uri
          The URI for the effigy.
 
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
Effigy(CompositeEntity container, java.lang.String name)
          Construct an effigy with the given name and container.
Effigy(Workspace workspace)
          Create a new effigy in the specified workspace with an empty string for its name.
 
Method Summary
protected  void _checkContainer(CompositeEntity container)
          Check that the specified container is of a suitable class for this entity, i.e., ModelDirectory or Effigy.
protected  void _removeEntity(ComponentEntity entity)
          Remove the specified entity from this container.
 void attributeChanged(Attribute attribute)
          If the argument is the identifier parameter, then set the title of all contained Tableaux to the value of the parameter; if the argument is the uri parameter, then check to see whether it is writable, and call setModifiable() appropriately.
 boolean closeTableaux()
          Close all tableaux contained by this effigy, and by any effigies it contains.
 TableauFactory getTableauFactory()
          Get a tableau factory that offers views of this effigy, or null if none has been specified.
 java.io.File getWritableFile()
          Return a writable file for the URI given by the uri parameter of this effigy, if there is one, or return null if there is not.
 boolean isModifiable()
          Return whether the model data is modifiable.
 boolean isModified()
          Return the value set by setModified(), or false if setModified() has not been called on this effigy or any effigy contained by the same top effigy (returned by topEffigy()).
 boolean isSystemEffigy()
          Return whether this effigy is a system effigy.
 int numberOfOpenTableaux()
          Return the total number of open tableau for this effigy effigy and all effigies it contains.
 void setContainer(CompositeEntity container)
          Override the base class so that tableaux contained by this object are removed before this effigy is removed from the ModelDirectory.
 void setModifiable(boolean flag)
          If the argument is false, the specify that that the model is not modifiable, even if the URI associated with this effigy is writable.
 void setModified(boolean modified)
          Record whether the data associated with this effigy has been modified since it was first read or last saved.
 void setSystemEffigy(boolean flag)
          Set the effigy to be a system effigy if the given flag is true.
 void setTableauFactory(TableauFactory factory)
          Specify a tableau factory that offers multiple views of this effigy.
 Tableau showTableaux()
          Make all tableaux associated with this effigy and any effigies it contains visible by raising or deiconifying them.
 Effigy topEffigy()
          Return the top-level effigy that (deeply) contains this one.
 void writeFile(java.io.File file)
          Write the model associated with this effigy to the specified file.
 
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, 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, 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

identifier

public StringAttribute identifier
The identifier for the effigy. The default value is "Unnamed".


uri

public URIAttribute uri
The URI for the effigy. The default value is null.

Constructor Detail

Effigy

public Effigy(Workspace workspace)
Create a new effigy in the specified workspace with an empty string for its name.

Parameters:
workspace - The workspace for this effigy.

Effigy

public Effigy(CompositeEntity container,
              java.lang.String name)
       throws IllegalActionException,
              NameDuplicationException
Construct an effigy with the given name and container.

Parameters:
container - The container.
name - The name of the effigy.
Throws:
IllegalActionException - If the entity cannot be contained by the proposed container.
NameDuplicationException - If the name coincides with an entity already in the container.
Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException
If the argument is the identifier parameter, then set the title of all contained Tableaux to the value of the parameter; if the argument is the uri parameter, then check to see whether it is writable, and call setModifiable() appropriately.

Overrides:
attributeChanged in class NamedObj
Parameters:
attribute - The attribute that changed.
Throws:
IllegalActionException - If the base class throws it.

closeTableaux

public boolean closeTableaux()
Close all tableaux contained by this effigy, and by any effigies it contains.

Returns:
False if the user cancels on a save query, and true if all tableaux are successfully closed.

getTableauFactory

public TableauFactory getTableauFactory()
Get a tableau factory that offers views of this effigy, or null if none has been specified. The tableau factory can be used to create visual renditions of or editors for the associated model. It can be used to find out what sorts of views are available for the model.

Returns:
A tableau factory offering multiple views.
See Also:
setTableauFactory(TableauFactory)

getWritableFile

public java.io.File getWritableFile()
Return a writable file for the URI given by the uri parameter of this effigy, if there is one, or return null if there is not. This will return null if the file does not exist, or it exists and is not writable, or the uri parameter has not been set.

Returns:
A writable file, or null if one cannot be created.

isModifiable

public boolean isModifiable()
Return whether the model data is modifiable. In this case, this is determined by checking whether the URI associated with this effigy can be written to. This will return false if either there is no URI associated with this effigy, or the URI is not a file, or the file is not writable or does not exist, or setModifiable() has been called with a false argument.

Returns:
False to indicate that the model is not modifiable.

isModified

public boolean isModified()
Return the value set by setModified(), or false if setModified() has not been called on this effigy or any effigy contained by the same top effigy (returned by topEffigy()). This method is intended to be used to keep track of whether the data in the file or URI associated with this data has been modified. The method is called by an instance of TableauFrame to determine whether it is safe to close.

Returns:
True if the data has been modified.
See Also:
setModifiable(boolean)

isSystemEffigy

public boolean isSystemEffigy()
Return whether this effigy is a system effigy. System effigies are not automatically removed when they have no tableaux.

Returns:
True if the model is a system effigy.

numberOfOpenTableaux

public int numberOfOpenTableaux()
Return the total number of open tableau for this effigy effigy and all effigies it contains.

Returns:
A non-negative integer giving the number of open tableaux.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException
Override the base class so that tableaux contained by this object are removed before this effigy is removed from the ModelDirectory. This causes the frames associated with those tableaux to be closed. Also, if the argument is null and there is a URI associated with this model, then purge any record of the model that the MoMLParser class is keeping so that future efforts to open the model result in re-parsing.

Overrides:
setContainer in class ComponentEntity
Parameters:
container - The directory in which to list this effigy.
Throws:
IllegalActionException - If the proposed container is not an instance of ModelDirectory, or if the superclass throws it.
NameDuplicationException - If the container already has an entity with the specified name.
See Also:
ComponentEntity.getContainer()

setModifiable

public void setModifiable(boolean flag)
If the argument is false, the specify that that the model is not modifiable, even if the URI associated with this effigy is writable. If the argument is true, or if this method is never called, then whether the model is modifiable is determined by whether the URI can be written to. Notice that this does not automatically result in any tableaux that are contained switching to being uneditable. But it will prevent them from writing to the URI.

Parameters:
flag - False to prevent writing to the URI.
See Also:
isModifiable()

setModified

public void setModified(boolean modified)
Record whether the data associated with this effigy has been modified since it was first read or last saved. If you call this with a true argument, then subsequent calls to isModified() will return true. This is used by instances of TableauFrame. This is recorded in the entity returned by topEntity(), which is the one associated with a file.

Parameters:
modified - True if the data has been modified.

setSystemEffigy

public void setSystemEffigy(boolean flag)
Set the effigy to be a system effigy if the given flag is true. System effigies are not removed automatically if they have no tableaux.


setTableauFactory

public void setTableauFactory(TableauFactory factory)
Specify a tableau factory that offers multiple views of this effigy. This can be used by a contained tableau to set up a View menu.

Parameters:
factory - A tableau factory offering multiple views.

showTableaux

public Tableau showTableaux()
Make all tableaux associated with this effigy and any effigies it contains visible by raising or deiconifying them. If there is no tableau contained directly by this effigy, then create one by calling createPrimaryTableau() in the configuration.

Returns:
The first tableau encountered, or a new one if there are none.

topEffigy

public Effigy topEffigy()
Return the top-level effigy that (deeply) contains this one. If this effigy is contained by another effigy, then return the result of calling this method on that other effigy; otherwise, return this effigy.

Returns:
The top-level effigy that (deeply) contains this one.

writeFile

public void writeFile(java.io.File file)
               throws java.io.IOException
Write the model associated with this effigy to the specified file. This base class throws an exception, since it does not know how to write model data. Derived classes should override this method to write model data.

Parameters:
file - The file to write to.
Throws:
java.io.IOException - If the write fails.

_checkContainer

protected void _checkContainer(CompositeEntity container)
                        throws IllegalActionException
Check that the specified container is of a suitable class for this entity, i.e., ModelDirectory or Effigy.

Parameters:
container - The proposed container.
Throws:
IllegalActionException - If the container is not of an acceptable class.

_removeEntity

protected void _removeEntity(ComponentEntity entity)
Remove the specified entity from this container. If this effigy is a system effigy and there are no remaining tableaux contained by this effigy or any effigy it contains, then remove this object from its container.

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