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 -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 insantiate KeplerInitializer:

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

Since:

Ptolemy II 8.0

Version:

$Id: ConfigurationApplication.java 57096 2010-01-29 17:39:33Z 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

(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

private int	_activeCount
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.
private boolean	_expectingClass
private static java.net.URL	_initialSpecificationURL
private java.util.List	_parameterNames
private java.util.List	_parameterValues
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	_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

ConfigurationApplication()
Empty constructor for subclasses to use.

ConfigurationApplication(java.lang.String[] args)
Parse the specified command-line arguments, instanting classes and reading files that are specified.

ConfigurationApplication(java.lang.String basePath, java.lang.String[] args)
Parse the specified command-line arguments, instanting classes and reading files that are specified.

Method Summary

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

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

_activeCount

private volatile int _activeCount

_expectingClass

private boolean _expectingClass

_parameterNames

private java.util.List _parameterNames

_parameterValues

private java.util.List _parameterValues

_initialSpecificationURL

private static java.net.URL _initialSpecificationURL

Constructor Detail

ConfigurationApplication

public ConfigurationApplication()

Empty constructor for subclasses to use.

ConfigurationApplication

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

Parse the specified command-line arguments, instanting 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, instanting 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.

Method Detail

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.

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.

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 IllegalActionException

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

Throws:

IllegalActionException - 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

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.