ptolemy.actor.gui
Class MoMLApplication

java.lang.Object
  extended byptolemy.actor.gui.MoMLApplication
Direct Known Subclasses:
PtExecuteApplication, PtolemyApplication, VergilApplication, VergilApplication

public class MoMLApplication
extends java.lang.Object

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.

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:

   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:
   ptolemy foo.xml -a 5 -y.b 10
   
would set the values of the two parameters.

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.91 2004/04/13 02:59:37 cxh Exp $
Author:
Edward A. Lee and Steve Neuendorffer, Contributor: Christopher Hylands
See Also:
Configuration
Accepted Rating:
Red (eal)
Proposed Rating:
Yellow (eal)

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  java.lang.String[][] _commandOptions
          The command-line options that take arguments.
protected  java.lang.String _commandTemplate
          The form of the command line.
protected  Configuration _config
           
protected  MoMLParser _parser
           
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 an 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)
          Read a Configuration from the URL given by the specified string.
protected  java.lang.String _usage()
          Return a string summarizing the command-line arguments.
static void main(java.lang.String[] args)
          Create a new instance of this application, passing it the command-line arguments.
static java.net.URL specToURL(java.lang.String spec)
          Given the name of a file or a URL, convert it to a URL.
 
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 java.lang.String[][] _commandOptions
The command-line options that take arguments.


_commandTemplate

protected java.lang.String _commandTemplate
The form of the command line.


_config

protected Configuration _config

_parser

protected MoMLParser _parser

_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

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.

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.
Throws:
java.io.IOException - If it cannot convert the specification to a URL.

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

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.

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.

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