Package ca.spatial.util

Class AppChooser

java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Window
java.awt.Frame
javax.swing.JFrame
ca.spatial.util.AppChooser
All Implemented Interfaces:
ActionListener, MouseListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible, ChangeListener, TreeSelectionListener, RootPaneContainer, WindowConstants
public final class AppChooser extends JFrame implements ActionListener, ChangeListener, MouseListener, TreeSelectionListener
This is the default class that is started from the Patchworks jar file when no other class name is specified on the command line. The AppChooser will display a window showing a list of application names. Choose the maximum amount of heap memory to allocate, and invoke an application by pressing on the Go button or by double-clicking on the application name.
The Application Launcher window

Drag-and-Drop

The Application Launcher menu window supports drag-and-drop operations. Data files and script files can be dropped on to the Application Launcher window to start up applications. The following file types are understood:
File extensions know by the Application Launcher
File extensionAction
.bshOpen the MapViewer application and run the script
.csv
.dbf
.shp		Open the MapViewer application and open the table
.pinOpen the Patchworks application and load the specified pin file.
Multiple files can be simultaneously dropped on the Application Launcher window. The folder location of the first dropped file will become the default location of the application. Relative pathnames will be resolved relative to the default folder location.

Default application properties

The user interface for the AppChooser supports viewing and setting the default application parameters. Right-click on an application name to view the default parameters.
Properties for Build Road Segments

Right-click on the 'Applications' menu item to view all default properties. Note that there are several properties for the launcher itself which allow custom settings to be passed to the Java environment.
Properties for the Application Launcher

Several of the launcher properties are:

Launcher properties
PropertyDescription
launcher.classpathA list of one or more jar files to be included in the java class path. Separate the jar file names with semicolons.
launcher.javaflagsA list of flags that will be passed along to the java process.
launcher.vmsizeThe heap size that will be set on the java command line. This is the same value that is shown on the AppChooser main menu.

Application properties are stored in a text file named patchworks.ini, normally found within the Documents/Patchworks folder. Although you may edit this text file take care not to introduce syntax errors that will prevent the application from initializing.

Batch scripting

This class also contains methods useful for batch scripting. In particular the invoke and invokeInline methods can be used to launch Patchworks tools from a BeanShell script. Both of these methods start the specified applications in a new execution process. These processes run when completed the process will exit. Running applications in a separate execution context provides isolation so that the data structures in one complex application do not interfere with another applicaiton. It also allows several processes to run simulataneously.

The invokeInline command pauses the current script, invokes the application in a new process, allows output from the new process to write to the current process terminal, and waits until the new process has completed before continuing the script. For example: 

AppChooser.invokeInline("ca.spatial.tracks.fvs.UnpackFVS",
     new String[] {"c:/Workspace/sample/yield/unpackConfig.yaml"});
The invoke command does the same as the invokeInline command, except that a new terminal is opened to contain the application output. Once the application has completed the terminal window can close. It is an option that the currently running script may continue to run, or will wait for the new process to finish. For example: 
AppChooser.invoke("ca.spatial.tracks.builder.Process",
     new String[] {"c:/Workspace/sample/data/fragments.dbf",
                   "c:/Workspace/sample/tracks",
                   "c:/Workspace/sample/tracks/forestModel.xml"}, true);

A true argument in the third position of the invoke command will start the application in a separate process and wait for the application to complete before continuing with the script. If a false is provided as the third parameter the script will continune to run after the application has has started, regardless of it's ongoing status.

The invoke command returns a Process object which may be used to monitor the status of the application. The Process object supports a Process.waitFor() method that will block until the application completes. This may be used to simultaneously start several applications and wait for all to complete before continuing. For example: 

// Build tracks
p1 = AppChooser.invoke("ca.spatial.tracks.builder.Process",
        new String[] {"c:/Workspace/sample/data/fragments.dbf",
                      "c:/Workspace/sample/tracks",
                      "c:/Workspace/sample/tracks/forestModel.xml"},
                       false);

// Build road network
p2 = AppChooser.invoke("ca.spatial.gis.vector.OutputSegments",
        new String[] {"c:/Workspace/sample/blocks/blocks.shp",
                      "CLUSTER",
                      "c:/Workspace/sample/roads/mills.shp",
                      "HAUL",
                      "1000",  // Search threshold of 1km
                      "ACCESS_",
                      "c:/Workspace/sample/roads/access.shp",
                      "c:/Workspace/sample/roads"},
                       false);

// Build topology
p3 = AppChooser.invoke("ca.spatial.gis.raster.ProximalTopology",
        new String[] {"c:/Workspace/sample/blocks/blocks.shp",
                      "10", "CLUSTER", "200",
                      "c:/Workspace/sample/blocks/blocks_topology_200r10.csv"},
                       false);

// Wait for all to complete
p1.waitFor();
p2.waitFor();
p3.waitFor();

// Carry on with the script
...
The Process object and the waitFor method are only useful when the false value has been passed in as the third argument. When the true value is used the process has terminated before the script resumes control.

Command line scripting

Applications can be invoked from the command line or from within other shell tools. Since Patchworks is a Java application, it runs under the control of the Java runtime environment. The command must start with the name of the Java program (typically java) and the path to the Patchworks "jar" file. Subsequent arguments include the class name of the application to start, and any arguments that should be passed along to the program.

In the following example, the java program loads the Patchworks jar file from thr standard location. The class name ca.spatial.mapview.MapViewer indicates that the MapViewer program should be started. The myScript.bsh is the name of a script file to be run, located relative to the current working directory. 

java -jar "C:/Program Files/Spatial Planning Systems/Patchworks/patchworks.jar" \
    ca.spatial.mapview.MapViewer myScript.bsh
Note that although this command is shown as being wrapped over two lines, this command should probably be entered on a single line (depends on the shell program being used).

The java command will begin to execute and will not return until the MapView program has been closed. Alternately the javaw program could have been used to launch the program without waiting for it to complete.

See Also:
Serialized Form

  • Method Details

    • mousePressed

      public void mousePressed​(MouseEvent e)
      Specified by:
      mousePressed in interface MouseListener

    • mouseClicked

      public void mouseClicked​(MouseEvent e)
      Specified by:
      mouseClicked in interface MouseListener

    • mouseEntered

      public void mouseEntered​(MouseEvent e)
      Specified by:
      mouseEntered in interface MouseListener

    • mouseExited

      public void mouseExited​(MouseEvent e)
      Specified by:
      mouseExited in interface MouseListener

    • mouseReleased

      public void mouseReleased​(MouseEvent e)
      Specified by:
      mouseReleased in interface MouseListener

    • stateChanged

      public void stateChanged​(ChangeEvent e)
      Specified by:
      stateChanged in interface ChangeListener

    • actionPerformed

      public void actionPerformed​(ActionEvent e)
      Specified by:
      actionPerformed in interface ActionListener

    • valueChanged

      public void valueChanged​(TreeSelectionEvent e)
      Specified by:
      valueChanged in interface TreeSelectionListener

    • invoke

      public static Process invoke​(String initialClass, String[] args)
      This method will invoke the application. The invocation will be done in a separate memory context, usually using an operating system 'exec' call. This method will start the process and without waiting for it to complete. A terminal window will be opened to display printed output from the command.

      This command is equivalent to 

      
 AppChooser.invoke(initialClass, args, false);
      Parameters:
      initialClass - The fully qualified name of the class to be invoked.
      args - A list of arguments to be passed to the main method of the class to be invoked.
      Returns:
      This method returns a reference to the invoked process. The Process object may be monitor to determine when the process has completed executing.

    • invoke

      public static Process invoke​(String initialClass, String[] args, boolean wait)
      This method will invoke the application. The invocation will be done in a separate process context, usually using an operating system 'exec' call. A terminal window will be opened to display printed output from the command.
      Parameters:
      initialClass - The fully qualified name of the class to be invoked.
      args - A list of arguments to be passed to the main method of the class to be invoked.
      wait - a boolean to indicate if this method should wait for the command to complete its execution before returning
      Returns:
      This method returns a reference to the invoked process. The Process object may be monitored to determine when the process has completed executing.

    • invokeInline

      public static void invokeInline​(String initialClass, String[] args)
      This method will invoke the requested class as an application. The invocation will be done in a separate process context, usually using an operating system 'exec' call. The command will run to completion before this method returns. Output will be written to the current terminal window.
      Parameters:
      initialClass - The fully qualified name of the class to be invoked.
      args - A list of arguments to be passed to the main method of the class to be invoked.

    • main

      public static void main​(String[] args)
      Entry point to run the application launcher. If run without arguments it will display the Application Launcher menu. If provided with arguments the first argument is the name of the class to launch (note that this class must have a static void main(String[] args) method. Subsequent arguments on the command line will be passed along to the invoked class.