Setting up a JAMS development environment

Introduction

The following instruction describes the installation of a JAMS/J2K development environment under Windows using Java 12, NetBeans IDE and the Tortoise SVN client. However, these are just examples and you can easily exchange these tools/versions by alternative ones. This guide is intended for users who want to look into the latest version of the JAMS software or its modelling components and which want to implement own extensions or modifications. Even though a Windows system is used in this example, all described steps are applicable on Linux or OS X based systems (using alternative SVN client software).

Recommended Software

  1. Java OpenJDK (https://jdk.java.net)
  2. NetBeans IDE (https://netbeans.apache.org)
  3. Tortoise SVN (https://tortoisesvn.net)

Downloading Sources

All sources and scripts of JAMS and its models are managed within a subversion (SVN) repository. Subversion is a software for version management of files and directories [1]. In order to access the JAMS-SVN, a valid SVN account is required. For read-only access the account “guest” with password “guest” can be used. For the installation of a JAMS development environment, first the required directories are created and filled with data from the SVN repository.

  1. create directory for JAMS (the example used below is c:\jams)
  2. create directory for JAMS models (the example used below is c:\jamsmodels)
  3. right click on c:\jams -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/jams/trunk as repository URL -> OK
  4. right click on c:\jamsmodels -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/jamsmodels/trunk as repository URL -> OK

Alternatively, you can download the latest source packages of JAMS and the J2K model components from the Download page.

Downloading Test Data

JAMS-SVN also containts a repository with a number of (test) datasets for various models. Please be aware that the overall amount of data in the modeldata repository might be very large. Only single sub-folders should therefore be downloaded.

  1. create directory for model data (the example used below is c:\jamsmodeldata)
  2. right click on c:\jamsmodeldata -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/modeldata as repository but don’t checkout yet
  3. use the browse button (right of the repository URL) to select your desired data folders (multiple folders can be entered by holding CTRL) -> OK

Directory Structure

As a result, directories for JAMS and JAMS models (and model data) are available after the last step. In addition to JAVA sources, the JAMS directory contains JAMS binary data and some Ant scripts [2] which can be used to compile JAMS without Netbeans (see below). Moreover, some pre-configured NetBeans projects are in the nbprojects subdirectory which allow an easy setup of a JAMS development environment.

The model directory contains sub-directories with JAVA sources of different model libraries, which include model components required for creating JAMS models. Again, this directory contains a nbprojects folder with pre-configured NetBeans projects.

The data directory contains various model workspaces including model definitions and input data.

Buidling JAMS and Models

Building with Ant Scripts

The JAMS build procedure is controlled by means of Apache Ant [2]. For the compilation  of JAMS, the installation of an IDE is not obligatory. Alternatively, Ant scripts located in c:\jams\build\build.xml can be used as an entry point to build all required libraries from the command line. A prerequisite for this is the installation of Apache Ant, which can be downloaded at http://ant.apache.org/bindownload.cgi.

The creation of JAMS libraries with Ant requires the following procedure:

  1. open command line in c:\jams\build,
  2. execute command “ant clean” for deletion of existing JAMS libraries,
  3. execute command “ant dojams” for creation of all JAMS libraries.

These steps can also be done by running the c:\jams\build\clean.bat and c:\jams\build\build-jams.bat Windows batch files. Upon successful compilation, the directory c:\jams\jams-bin will be filled with libraries which contain all necessary system classes (subdirectory lib) and different standard components (subdirectory components). Together with the external libraries in c:\jams\ext they make available the JAMS API, the runtime environment, and different graphical user interfaces for the creation and execution of models or the evaluation of model results.

Building with NetBeans

JAMS

For JAMS, pre-configured NetBeans projects are stored in the c:\jams\nbprojects folder. To open them from NetBeans, select File -> Open Project… and choose the desired JAMS sub-project from c:\jams\nbprojects. In order to compile all JAMS sources, open the “jams-starter” project, right-click on “jams-starter” and choose Clean and Build. When doing so, all necessary libraries are created and automatically copied to c:\jams\jams-bin as described in the last section.

Models (e.g. J2K)

For many models (e.g. J2K, J2K-S and J2Kg), pre-configured NetBeans projects are already in the SVN repository. To open them, select File -> Open Project… and choose the desired project from within c:\jamsmodels\nbprojects. If the “Reference Problems” dialog window pops up upon opening the project, use the “Resolve Problems…” button to specify the storage location of the “jams-api.jar” and “jams-main.jar” libraries which you can find in the JAMS library folder (e.g. c:\jams\jams-bin\lib). After compiling a model project, the resulting libraries are stored in the c:\jamsmodels\nbprojects\components subfolder or in the dist subfolder of the model’s project folder (e.g. c:\jamsmodels\nbprojects\J2K_base\dist).

For other models without pre-configured projects the following steps are needed to create a new project:

  1. In NetBeans: File -> New Project -> Java Project with Existing Sources
  2. Indicate project name (e.g. J2K) and directory (e.g. c:\jamsmodels\nbprojects\J2Kg, the compiled classes and the JAR file are stored here) -> Next
  3. Source Package Folder -> Add Folder… -> c:\jamsmodels\J2Kg\src -> OK
  4. Press Finish
  5. Include libraries: right click on J2Kg/Libraries -> Add JAR/Folder… and select the JAMS libraries jams-api.jar and jams-main.jar from c:\jams\jams-bin\lib.
  6. Right click on J2Kg -> Clean and Build (Compile project and create J2Kg.jar in c:\jamsmodels\nbprojects\J2Kg\dist\)

Template for JAMS Components

A component template for NetBeans can be found at c:\jams\template\JAMSComponent.java (adapt as needed!). The integration into NetBeans is done as follows:

  1. Tools -> Templates -> Java -> Add…
  2. Select above-mentioned file -> Add

Afterwards, “JAMSComponent” can be selected as a file type when creating a new class.

Running JAMS/J2K

In order to run JAMS, the  jams-starter project is selected as main project (Run -> Set Main Project in the NetBeans menu). The jams-starter project does not contain any Java sources but serves as an entry point for building and starting JAMS. For the latter purpose, it contains three predefined starter configurations, i.e.

  1. CmdLine: run JAMS in command line mode without any GUI
  2. JAMS Launcher: run the JAMS Launcher GUI allowing to load and run models
  3. JUICE: run the JAMS Builder allowing to create, load, configure and run models

To use any of these configurations, select it using the drop-down box in the NetBeans toolbar. The project is started using F6, the green start button in the NetBeans toolbar, or the context menu (right click on jams-starter -> Run). The arguments given at the start can be modified as follows:

  1. Right click on jams-starter -> Properties -> Run
  2. Under “Arguments” insert the following: -c <complete path of a configuration file> -m <complete path of a model definition file>. A list of valid arguments will be shown in the default output when using the arguments -h or –help.

In the default configuration, the JAMS Launcher or JUICE is supposed to be opened. From within any these two, a model can be loaded via File -> Load model….

The execution of most models also requires the provision of additional libraries (e.g. J2K_base.jar, J2K_ext.jar and jams-components.jar). Via Edit -> Change settings… in JAMS, additional libraries can be indicated that are considered for the model execution. When closing JAMS, the settings are automatically saved in the JAMS system configuration.

Note: After modifying model components, the JAR file always has to be re-generated with the components before the execution. (Step 6 in “Compiling JAMS and Models“)!