ptolemy.actor.gui

Class ConfigurationApplication

java.lang.Object

ptolemy.actor.gui.ConfigurationApplication

All Implemented Interfaces:

ExecutionListener

Direct Known Subclasses:

MoMLApplication

public class ConfigurationApplication
extends java.lang.Object
implements ExecutionListener

An application that reads one or more files specified on the command line, or instantiates one or more Java classes specified by the -class option. If one of these files is an XML file that defines a Configuration, or one of the classes is an instance of Configuration, then all subsequent files will be read by delegating to the Configuration, invoking its openModel() method. A command-line file is assumed to be a MoML file or a file that can be opened by the specified configuration.

For example, this command uses the HyVisual configuration to open a model:

 $PTII/bin/moml $PTII/ptolemy/configs/hyvisual/configuration.xml $PTII/ptolemy/domains/ct/demo/StickyMasses/StickyMasses.xml
 

If a Ptolemy model is instantiated on the command line, either by giving a MoML file or a -class argument, then parameters of that model can be set on the command line. The syntax is:

 $PTII/bin/ptolemy modelFile.xml -parameterName value
 

where parameterName is the name of a parameter relative to the top level of a model or the director of a model. For instance, if foo.xml defines a toplevel entity named x and x contains an entity named y and a parameter named a, and y contains a parameter named b, then:

 $PTII/bin/ptolemy foo.xml -a 5 -y.b 10
 

would set the values of the two parameters.

Note that strings need to have double quotes converted to " so to set a parameter named c to the string "bar" it might be necessary to do something like:

 $PTII/bin/ptolemy foo.xml -a 5 -y.b 10 -c ""bar""
 

The " is necessary to convert the double quote to something safe to in an XML file. The backslashes are necessary to protect the & and ; from the shell in the shell script.

Note that the ptolemy.actor.parameters.ParameterSet attribute is a better way to set parameters at run time. ParameterSet is an attribute that reads multiple values from a file and sets corresponding parameters in the container.

The -class option can be used to specify a Java class to be loaded. The named class must have a constructor that takes a Workspace as an argument. In the example below, $PTII/ptolemy/domains/sdf/demo/Butterfly/Butterfly.java is a class that has a constructor Butterfly(Workspace).

 $PTII/bin/ptolemy -class ptolemy.domains.sdf.demo.Butterfly.Butterfly
 

Note that -class is very well tested now that we have use MoML for almost all models.

Derived classes may provide default configurations. In particular, the protected method _createDefaultConfiguration() is called before any arguments are processed to provide a default configuration for those command-line command-line arguments. In this base class, that method returns null, so no default configuration is provided.

If no arguments are given at all, then a default configuration is instead obtained by calling the protected method _createEmptyConfiguration(). In this base class, that method also returns null, so calling this with no arguments will not be very useful. No configuration will be created and no models will be opened. Derived classes can specify a configuration that opens some welcome window, or a blank editor.

This class read the following parameters from the configuration:

_applicationInitializer

A StringParameter that names a class to be instantiated. Kepler uses this parameter to instantiate KeplerInitializer:

 >property name="_applicationInitializer"
         class="ptolemy.data.expr.StringParameter"
         value="org.kepler.gui.KeplerInitializer"/<

Since:

Ptolemy II 8.0

Version:

$Id: ConfigurationApplication.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Edward A. Lee and Steve Neuendorffer, Contributor: Christopher Hylands

See Also:

Configuration

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	ConfigurationApplication.ConfigurationFilenameFilter Look for directories that contain files named configuration.xml and intro.htm.
static class	ConfigurationApplication.IgnoreErrorHandler Error Handler that ignore errors.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_basePath The base path of the configuration directory, usually "ptolemy/configs" for Ptolemy II, but subclasses might have configurations in a different directory.
protected java.lang.String[][]	_commandFlagsWithDescriptions The command-line options that are either present or not.
protected static java.lang.String[][]	_commandOptions The command-line options that take arguments.
protected java.lang.String	_commandTemplate The form of the command line.
protected Configuration	_configuration The configuration model of this application.
protected boolean	_exit Indicator that -runThenExit was requested.
protected MoMLParser	_parser The parser used to construct the configuration.
protected static boolean	_printPDF If true, then print to PDF.
protected boolean	_run If true, then -run was specified on the command line.
protected boolean	_run20x If true, then -run20x was specified on the command line.
protected boolean	_statistics If true, then -statistics was specified on the command line.
protected static boolean	_test If true, then auto exit after a few seconds.

Constructor Summary

Constructors

Constructor and Description
ConfigurationApplication() Instantiate a ConfigurationApplication.
ConfigurationApplication(java.lang.String[] args) Parse the specified command-line arguments, instantiating classes and reading files that are specified.
ConfigurationApplication(java.lang.String basePath, java.lang.String[] args) Parse the specified command-line arguments, instantiating classes and reading files that are specified.
ConfigurationApplication(java.lang.String basePath, java.lang.String[] args, MessageHandler messageHandler, ErrorHandler errorHandler) Parse the specified command-line arguments, instantiating classes and reading files that are specified.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	_configurationUsage(java.lang.String commandTemplate, java.lang.String[][] commandOptions, java.lang.String[] commandFlags) Return a string summarizing the command-line arguments, including any configuration directories in a base path, typically "ptolemy/configs".
protected java.lang.String	_configurationUsage(java.lang.String commandTemplate, java.lang.String[][] commandOptions, java.lang.String[][] commandFlagsWithDescriptions) Return a string summarizing the command-line arguments, including any configuration directories in a base path, typically "ptolemy/configs".
protected Configuration	_createDefaultConfiguration() Return a default Configuration, or null to do without one.
protected Configuration	_createEmptyConfiguration() Return a default Configuration to use when there are no command-line arguments, or null to do without one.
protected void	_initializeApplication() Perform any application specific initialization.
protected Tableau	_openModel(NamedObj entity) Open the specified Ptolemy II model.
protected Tableau	_openModel(java.net.URL base, java.net.URL in, java.lang.String identifier) Open the specified URL.
protected boolean	_parseArg(java.lang.String arg) Parse a command-line argument.
protected void	_parseArgs(java.lang.String[] args) Parse the command-line arguments.
protected void	_printPDF() Print each effigy to the first printer with the string "PDF" in the name.
protected Configuration	_readConfiguration(java.net.URL specificationURL) Deprecated. Use readConfiguration() instead.
protected java.lang.String	_usage() Return a string summarizing the command-line arguments.
static void	closeModelWithoutSavingOrExiting(CompositeEntity model) Close the model without saving or exiting.
void	executionError(Manager manager, java.lang.Throwable throwable) Reduce the count of executing models by one.
void	executionFinished(Manager manager) Reduce the count of executing models by one.
static void	main(java.lang.String[] args) Create a new instance of this application, passing it the command-line arguments.
void	managerStateChanged(Manager manager) Do nothing.
java.util.List	models() Return a list of the Ptolemy II models that were created by processing the command-line arguments.
static TypedCompositeActor	openModel(java.lang.String modelFileName) Deprecated. Use #openModelOrEntity(String) instead and handle the case where the modelFileName refers to a HTML or text file or an interface diagram.
static CompositeEntity	openModelOrEntity(java.lang.String modelFileName) Open a model and display it.
static Configuration	readConfiguration(java.net.URL specificationURL) Read a Configuration from the URL given by the specified string.
void	runModels() Start the models running, each in a new thread, then return.
static java.net.URL	specToURL(java.lang.String spec) Given the name of a file or a URL, convert it to a URL.
static void	throwArgsException(java.lang.Throwable cause, java.lang.String[] args) Throw an exception that includes the elements of the args parameter.
void	waitForFinish() Wait for all executing runs to finish, then return.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_basePath

protected java.lang.String _basePath

The base path of the configuration directory, usually "ptolemy/configs" for Ptolemy II, but subclasses might have configurations in a different directory.

_commandFlagsWithDescriptions

protected java.lang.String[][] _commandFlagsWithDescriptions

The command-line options that are either present or not.

_commandOptions

protected static java.lang.String[][] _commandOptions

The command-line options that take arguments.

_commandTemplate

protected java.lang.String _commandTemplate

The form of the command line.

_configuration

protected Configuration _configuration

The configuration model of this application.

_exit

protected boolean _exit

Indicator that -runThenExit was requested.

_parser

protected MoMLParser _parser

The parser used to construct the configuration.

_printPDF

protected static boolean _printPDF

If true, then print to PDF.

_run

protected boolean _run

If true, then -run was specified on the command line.

_run20x

protected boolean _run20x

If true, then -run20x was specified on the command line.

_statistics

protected boolean _statistics

If true, then -statistics was specified on the command line.

_test

protected static boolean _test

If true, then auto exit after a few seconds.

Constructor Detail

ConfigurationApplication

public ConfigurationApplication()

Instantiate a ConfigurationApplication. This constructor is probably not useful by itself, it is for use by subclasses.

The HandSimDroid work in $PTII/ptserver uses dependency injection to determine which implementation actors such as Const and Display to use. This method reads the ptolemy/actor/ActorModule.properties file.

ConfigurationApplication

public ConfigurationApplication(java.lang.String[] args)
                         throws java.lang.Exception

Parse the specified command-line arguments, instantiating classes and reading files that are specified.

Parameters:

args - The command-line arguments.

Throws:

java.lang.Exception - If command line arguments have problems.

ConfigurationApplication

public ConfigurationApplication(java.lang.String basePath,
                                java.lang.String[] args)
                         throws java.lang.Exception

Parse the specified command-line arguments, instantiating classes and reading files that are specified.

Parameters:

basePath - The basePath to look for configurations in, usually "ptolemy/configs", but other tools might have other configurations in other directories

args - The command-line arguments.

Throws:

java.lang.Exception - If command line arguments have problems.

ConfigurationApplication

public ConfigurationApplication(java.lang.String basePath,
                                java.lang.String[] args,
                                MessageHandler messageHandler,
                                ErrorHandler errorHandler)
                         throws java.lang.Exception

Parse the specified command-line arguments, instantiating classes and reading files that are specified.

Parameters:

basePath - The basePath to look for configurations in, usually "ptolemy/configs", but other tools might have other configurations in other directories

args - The command-line arguments.

messageHandler - The message handler.

errorHandler - the MoML error handler.

Throws:

java.lang.Exception - If command line arguments have problems.

Method Detail

closeModelWithoutSavingOrExiting

public static void closeModelWithoutSavingOrExiting(CompositeEntity model)
                                             throws IllegalActionException,
                                                    NameDuplicationException

Close the model without saving or exiting.

The caller of this method should be in the Swing Event Thread. Typically, this is done with code like:

   Runnable openModelAction = new Runnable() {
       public void run() {
           try {
               ConfigurationApplication.closeModel(model[0])
           } catch (Exception ex) {
               throw new RuntimeException(ex);
           }
       }
   };
   SwingUtilities.invokeAndWait(openModelAction);
  

This method is primarily used for testing.

Parameters:

model - The TypedCompositeActor to be closed. Typically, this comes from openModel(String).

Throws:

IllegalActionException - If the model cannot be closed.

NameDuplicationException - If the model cannot be closed.

See Also:

openModel(String), openModel(String)

executionError

public void executionError(Manager manager,
                           java.lang.Throwable throwable)

Reduce the count of executing models by one. If the number of executing models drops to zero, then notify threads that might be waiting for this event.

Specified by:

executionError in interface ExecutionListener

Parameters:

manager - The manager calling this method.

throwable - The throwable being reported.

executionFinished

public void executionFinished(Manager manager)

Reduce the count of executing models by one. If the number of executing models drops ot zero, then notify threads that might be waiting for this event.

Specified by:

executionFinished in interface ExecutionListener

Parameters:

manager - The manager calling this method.

main

public static void main(java.lang.String[] args)

Create a new instance of this application, passing it the command-line arguments.

For example to use the full configuration to open a model:

  java -classpath $PTII ptolemy.actor.gui.ConfigurationApplication \
     $PTII ptolemy/configs/full/configuration.xml \
     $PTII/ptolemy/moml/demo/modulation.xml
  

However, it better to use MoMLApplication, which sets the native Java look and feel and uses a better error handler, or to use MoMLSimpleApplication, with non-graphical models.

Parameters:

args - The command-line arguments.

managerStateChanged

public void managerStateChanged(Manager manager)

Do nothing.

Specified by:

managerStateChanged in interface ExecutionListener

Parameters:

manager - The manager calling this method.

See Also:

Manager.getState()

models

public java.util.List models()

Return a list of the Ptolemy II models that were created by processing the command-line arguments.

Returns:

A list of instances of NamedObj.

openModel

@Deprecated
public static TypedCompositeActor openModel(java.lang.String modelFileName)
                                                 throws java.lang.Throwable

Deprecated. Use #openModelOrEntity(String) instead and handle the case where the modelFileName refers to a HTML or text file or an interface diagram.

Open a model and display it.

The caller of this method should be in the Swing Event Thread. Typically, this is done with code like:

   Runnable openModelAction = new Runnable() {
       public void run() {
           try {
               model[0] = ConfigurationApplication.openModel(modelFileName);
           } catch (Exception ex) {
               throw new RuntimeException(ex);
           }
       }
   };
   SwingUtilities.invokeAndWait(openModelAction);
  

This method is primarily used for testing. To get the ptolemy.vergil.basic.BasicGraphFrame from a model returned by this method, see ptolemy.vergil.basic.BasicGraphFrame.getBasicGraphFrame().

Parameters:

modelFileName - The pathname to the model. Usually the pathname starts with "$CLASSPATH". The name of the top level of the model must match the base name of the modelFileName. Thus $CLASSPATH/Foo.xml should have a toplevel named "Foo". If the name of the model and the name of the top level do not match, then the last CompositeActor is returned.

Returns:

The model that was opened.

Throws:

java.lang.Throwable - If the model cannot be opened.

See Also:

closeModelWithoutSavingOrExiting(CompositeEntity)

openModelOrEntity

public static CompositeEntity openModelOrEntity(java.lang.String modelFileName)
                                         throws java.lang.Throwable

Open a model and display it.

The caller of this method should be in the Swing Event Thread. Typically, this is done with code like:

   Runnable openModelAction = new Runnable() {
       public void run() {
           try {
               model[0] = ConfigurationApplication.openModelOrEntity(modelFileName);
           } catch (Exception ex) {
               throw new RuntimeException(ex);
           }
       }
   };
   SwingUtilities.invokeAndWait(openModelAction);
  

This method is primarily used for testing. To get the ptolemy.vergil.basic.BasicGraphFrame from a model returned by this method, see ptolemy.vergil.basic.BasicGraphFrame.getBasicGraphFrame().

Parameters:

modelFileName - The pathname to the model. Usually the pathname starts with "$CLASSPATH". The name of the top level of the model must match the base name of the modelFileName. Thus $CLASSPATH/Foo.xml should have a toplevel named "Foo". If the name of the model and the name of the top level do not match, then the last CompositeActor is returned.

Returns:

The model that was opened.

Throws:

java.lang.Throwable - If the model cannot be opened.

See Also:

closeModelWithoutSavingOrExiting(CompositeEntity)

readConfiguration

public static Configuration readConfiguration(java.net.URL specificationURL)
                                       throws java.lang.Exception

Read a Configuration from the URL given by the specified string. The URL may absolute, or relative to the Ptolemy II tree root, or in the classpath. To convert a String to a URL suitable for use by this method, call specToURL(String).

If there is an _applicationInitializer parameter, then instantiate the class named by that parameter. The _applicationInitializer parameter contains a string that names a class to be initialized.

If the configuration has already been read in, then the old configuration will be deleted. Note that this may exit the application.

Parameters:

specificationURL - A string describing a URL.

Returns:

A configuration.

Throws:

java.lang.Exception - If the configuration cannot be opened, or if the contents of the URL is not a configuration.

runModels

public void runModels()
               throws KernelException

Start the models running, each in a new thread, then return.

Throws:

KernelException - If the manager throws it.

specToURL

public static java.net.URL specToURL(java.lang.String spec)
                              throws java.io.IOException

Given the name of a file or a URL, convert it to a URL. This first attempts to do that directly by invoking a URL constructor. If that fails, then it tries to interpret the spec as a file name on the local file system. If that fails, then it tries to interpret the spec as a resource accessible to the class loader, which uses the classpath to find the resource. If that fails, then it throws an exception. The specification can give a file name relative to current working directory, or the directory in which this application is started up.

Parameters:

spec - The specification.

Returns:

the URL.

Throws:

java.io.IOException - If it cannot convert the specification to a URL.

throwArgsException

public static void throwArgsException(java.lang.Throwable cause,
                                      java.lang.String[] args)
                               throws java.lang.Exception

Throw an exception that includes the elements of the args parameter.

Parameters:

cause - The throwable that caused the problem.

args - An array of Strings.

Throws:

java.lang.Exception - Always thrown

waitForFinish

public void waitForFinish()

Wait for all executing runs to finish, then return.

_configurationUsage

protected java.lang.String _configurationUsage(java.lang.String commandTemplate,
                                               java.lang.String[][] commandOptions,
                                               java.lang.String[] commandFlags)

Return a string summarizing the command-line arguments, including any configuration directories in a base path, typically "ptolemy/configs". Some subclasses of this class use configurations from ptolemy/configs. For example, if ptolemy/configs/full/configuration.xml exists then -full is a legitimate argument.

Parameters:

commandTemplate - The form of the command line

commandOptions - Command-line options that take arguments.

commandFlags - An array of Strings that list command-line options that are either present or not.

Returns:

A usage string.

See Also:

StringUtilities.usageString(String, String [][], String [])

_configurationUsage

protected java.lang.String _configurationUsage(java.lang.String commandTemplate,
                                               java.lang.String[][] commandOptions,
                                               java.lang.String[][] commandFlagsWithDescriptions)

Return a string summarizing the command-line arguments, including any configuration directories in a base path, typically "ptolemy/configs". Some subclasses of this class use configurations from ptolemy/configs. For example, if ptolemy/configs/full/configuration.xml exists then -full is a legitimate argument.

Parameters:

commandTemplate - The form of the command line

commandOptions - Command-line options that take arguments.

commandFlagsWithDescriptions - A 2xM array of Strings that list command-line options that are either present or not and a description of what the command line option does.

Returns:

A usage string.

See Also:

StringUtilities.usageString(String, String [][], String [][])

_initializeApplication

protected void _initializeApplication()

Perform any application specific initialization. In this base class, do nothing. Derived classes can perform initialization. This method is called by early in the constructor, so the object may not be completely constructed, so derived classes should not access fields from a parent class.

_createDefaultConfiguration

protected Configuration _createDefaultConfiguration()
                                             throws java.lang.Exception

Return a default Configuration, or null to do without one. This configuration will be created before any command-line arguments are processed. If there are no command-line arguments, then the default configuration is given by _createEmptyConfiguration() instead. This method merges the compile-time configuration file values from StringUtilities.mergePropertiesFile(). Subclasses should call PtolemyPreferences.setDefaultPreferences(Configuration).

Returns:

null

Throws:

java.lang.Exception - Thrown in derived classes if the default configuration cannot be opened.

_createEmptyConfiguration

protected Configuration _createEmptyConfiguration()
                                           throws java.lang.Exception

Return a default Configuration to use when there are no command-line arguments, or null to do without one. This base class returns the configuration returned by _createDefaultConfiguration().

Returns:

null

Throws:

java.lang.Exception - Thrown in derived classes if the empty configuration cannot be opened.

_openModel

protected 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

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

_parseArg

protected boolean _parseArg(java.lang.String arg)
                     throws java.lang.Exception

Parse a command-line argument.

Parameters:

arg - The command-line argument to be parsed.

Returns:

True if the argument is understood, false otherwise.

Throws:

java.lang.Exception - If something goes wrong.

_parseArgs

protected void _parseArgs(java.lang.String[] args)
                   throws java.lang.Exception

Parse the command-line arguments.

Parameters:

args - The command-line arguments to be parsed.

Throws:

java.lang.Exception - If an argument is not understood or triggers an error.

_printPDF

protected void _printPDF()
                  throws java.lang.Exception

Print each effigy to the first printer with the string "PDF" in the name. For this to work, the frame associated with the tableau must implement Printable or Pageable. As a side effect, for better printing, the background color is set to white.

Throws:

java.lang.Exception - If a printer with the string "PDF" cannot be found or if the job cannot be set to the PDF print service or if there is another problem printing.

_readConfiguration

@Deprecated
protected Configuration _readConfiguration(java.net.URL specificationURL)
                                                throws java.lang.Exception

Deprecated. Use readConfiguration() instead.

Read a Configuration from the URL given by the specified string. The URL may absolute, or relative to the Ptolemy II tree root, or in the classpath. To convert a String to a URL suitable for use by this method, call specToURL(String).

Parameters:

specificationURL - A string describing a URL.

Returns:

A configuration.

Throws:

java.lang.Exception - If the configuration cannot be opened, or if the contents of the URL is not a configuration.

_usage

protected java.lang.String _usage()

Return a string summarizing the command-line arguments.

Returns:

A usage string.