ptolemy.actor.gui
Class MoMLApplication

java.lang.Object
  ptolemy.actor.gui.MoMLApplication

All Implemented Interfaces:

ExecutionListener

Direct Known Subclasses:

PtExecuteApplication, PtolemyApplication, VergilApplication

public class MoMLApplication
extends java.lang.Object
implements ExecutionListener

This is 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 be carefully backslashed, 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 reason the backslashes are necessary is because moml is a shell script which tends to strip off the double quotes. 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.

Since:

Ptolemy II 0.4

Version:

$Id: MoMLApplication.java,v 1.148.4.2 2008/01/29 07:35:36 cxh Exp $

Author:

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

See Also:

Configuration

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

static class

MoMLApplication.IgnoreErrorHandler Error Handler that ignore errors.

Field Summary

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[]	_commandFlags 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 boolean	_run If true, then -run was specified on the command line.
protected static boolean	_test If true, then auto exit after a few seconds.

Constructor Summary

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

MoMLApplication(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 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 boolean	_parseArg(java.lang.String arg) Parse a command-line argument.
protected void	_parseArgs(java.lang.String[] args) Parse the command-line arguments.
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.

_commandFlags

protected java.lang.String[] _commandFlags

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.

_run

protected boolean _run

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

_test

protected static boolean _test

If true, then auto exit after a few seconds.

Constructor Detail

MoMLApplication

public MoMLApplication(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.

MoMLApplication

public MoMLApplication(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 - Command-line options that are either present or not.

Returns:

A usage string.

See Also:

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

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

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

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