Package ptolemy.actor.gui

Class Configuration

  • All Implemented Interfaces:
    java.lang.Cloneable, ApplicationConfigurer, InstanceOpener, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class Configuration
extends CompositeEntity
implements ApplicationConfigurer, InstanceOpener
    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$
    Author:
    Steve Neuendorffer and Edward A. Lee
    See Also:
    EffigyFactory, ModelDirectory, Tableau, TextEditorTableau
    Pt.AcceptedRating:
    Yellow (celaine)
    Pt.ProposedRating:
    Green (eal)

    • 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

    • 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

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

      • checkCloneFields

        public static java.lang.String checkCloneFields​(NamedObj namedObj)
                                         throws java.lang.CloneNotSupportedException,
                                                java.lang.IllegalAccessException,
                                                IllegalActionException,
                                                NameDuplicationException,
                                                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.
        IllegalActionException
        NameDuplicationException

      • 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<Configuration> 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.

      • getStringParameterAsClass

        public java.lang.Object getStringParameterAsClass​(java.lang.String parameterName,
                                                  java.lang.Class[] constructorParameterTypes,
                                                  java.lang.Object[] constructorParameterClass)
                                           throws java.lang.ClassNotFoundException,
                                                  java.lang.IllegalAccessException,
                                                  IllegalActionException,
                                                  java.lang.InstantiationException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.NoSuchMethodException
        Instantiate the class named by a StringParameter in the configuration.
        Parameters:
        parameterName - The name of the StringParameter in the configuration.
        constructorParameterTypes - An array of parameter types, null if there are no parameters
        constructorParameterClass - An array of objects to pass to the constructor.
        Returns:
        an instance of the class named by parameterName, or null if the configuration does not contain a parameter by that name.
        Throws:
        java.lang.ClassNotFoundException - If the class named by parameterName cannot be found.
        java.lang.IllegalAccessException - If the constructor is not accessible.
        IllegalActionException - If thrown while reading the parameter named by parameterName.
        java.lang.InstantiationException - If the object cannot be instantiated
        java.lang.reflect.InvocationTargetException - If there is problem invoking the constructor.
        java.lang.NoSuchMethodException - If there is no constructor with the type.

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

      • openAnInstance

        public void openAnInstance​(NamedObj entity)
                    throws IllegalActionException,
                           NameDuplicationException
        Open the specified instance. A derived class looks for the instance, and if the instance already has open tableaux, then put those in the foreground 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.
        Specified by:
        openAnInstance in interface InstanceOpener
        Parameters:
        entity - The entity to open.
        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)
                     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).

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