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

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.

A landscape partitioning application used to automatically create compartments
Raster GIS operators and supporting classes
Vector GIS operators and supporting classes
The MapViewer application and supporting classes
Symbology support classes for the MapViewer application
The Patchworks Query Language parser and supporting classes
The Patchworks application and supporting classes
Report templates and report writer functions
Access classes for spatial and tabular data
INFO table data access classes
Common classes used by model translators
The MatrixBuilder application and supporting classes
An application to translate SFMM models to Patchworks
An application to translate Woodstock models to Patchworks
Utility classes used in common by the Patchworks system