Patchworks v1.0 Application Programming Interface Specification
The Patchworks™ Java API
This documentation describes the Application Programming Interface to the Patchworks™ forest simulation modeling system. The API contains Java classes and methods that are used to build models, run simulations and generate output. This API is intended to launch Patchworks applications and to customize the behaviour of Patchworks applications using the scripting environment.
Launching Applications
The Patchworks™ system is built on the Java platfrom and executes under the Java Runtime Environment (JRE). In order to run Patchworks you must ensure that the Java 1.8 JRE is installed. Refer to the installation instructions in the Patchworks User Guide and Reference for more information.
Patchworks programs may be started by point-and-click using the Patchworks Application Launcher, or they may be start by using a command line interface (either in a script or interactively).
From the Application Launcher
Most people using the Patchworks™ system will start programs using the Patchworks Application Launcher. This is the default program that is invoked when the Patchworks program is started, or when the Application Launcher is selected from the Start menu.
When starting using the Application Launcher most program will present a 'wizard' interface to collect the required parameters.
From the command line
Patchworks top level applications (such as Patchworks or the MapViewer) may be started directly from the command line by specifying the fully qualified name of the class that contains the main method, along with any required or optional parameters. For example:
java -Xmx2G -jar "c:/Program Files/Spatial Planning Systems/Patchworks/patchworks.jar" ca.spatial.patchworks.Patchworks model01.pin
If the required parameters are provided on the command line the program will begin execution right away. If the parameters are not specified then a 'wizard' interface will be presented to collect the required information.
Other Java command line options may be required, such as to set the amount of heap space available to the JVM.
Customization using scripts
Patchworks applications permit customization using scripts to invoke classes and methods from the Patchworks API as well as from the Java API's and other third party libraries. For most people the automated code generators (e.g. Show Constructor) will provide a suitable starting point for customization. This API documentation will provide further details about the classes and methods that can be called and the parameters that can adjusted.
The Patchworks runtime will automatically import many of the popular packages. You may need to explicitly import less commonly used packages before use.