Brief instruction JAMS development

Revision as of 13:33, 17 November 2011

Introduction

The following instruction describes the installation of a JAMS/J2000 development environment using Tortoise (SVN client) and NetBeans (Java-IDE). Of course, alternative software can be used as well.

This instruction is intended for users who extend JAMS, develop new components or who just like to know what exactly happens in JAMS and/or the process components. Moreover, setting up the development environment helps to find and eliminate error sources.

Installation of Required Software

1. Tortoise SVN (http://tortoisesvn.tigris.org)
2. NetBeans/Java (http://java.sun.com/javase/downloads/netbeans.html)

Creating Directories

Downloading Data

All JAVA sources and scripts for JAMS and its models as well as a series of model datasets are managed within a subversion (SVN) repository [1]. Subversion is a software for version management of files and directories [2]. In order to access the JAMS-SVN, a valid SVN account is required. For the installation of a JAMS work 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 models (the exmaple used belwo is c:\jamsmodels)
3. create directory for model data (the example used below is c:\jamsmodeldata)
4. right click on c:\jams -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/jams/trunk as repository URL -> OK
5. right click on c:\jamsmodels -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/jamsmodels/trunk as repository URL -> OK
6. right click on c:\jamsmodeldata -> SVN Checkout and indicate http://svn.geogr.uni-jena.de/svn/modeldata as repository URL -> OK

Directory Structure

As a result, three directories for JAMS, 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 [3] which can be used to create them easily. Moreover, some pre-configured NetBeans projects are in the directory which allow an easy installation 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.

The data directory contains model definitions and input data for different model applications.

Compiling JAMS and Models

JAMS Binary Packages

Creating new JAMS libraries is not necessarily required since the JAMS SVN repository contains a current version of all necessary libraries (directory c:\jams\lib). Creating a JAMS development environment and transferring JAMS libraries is only required if JAMS or its standard components are supposed to be modified or debugged. If only components of JAMS models are supposed to be modified, the next step is shown in section: Models.

Ant Scripts

In order to create a current version of JAMS libraries, the installation of a development environment is not obligatory. An alternative Ant script can be used via c:\jams\build\build.xml, which centrally carries out the transformation and compilation of all required resources. The 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 the directory c:\jams\build,
2. call command "ant clean" for deletion of existing JAMS libraries,
3. call command "ant" for creation of all JAMS libraries.

These steps can also be carried out by executing a batch file via c:\jams\build\build.bat. Finally, the directory c:\jams\bin will be filled with JAMS libraries which contain all necessary system classes and different standard model components. Together with the external libraries in c:\jams\lib they make available the JAMS API, the runtime environment, and different graphic surfaces for the creation and execution of models or the evaluation of model results.

Installing the Development Environment

JAMS

For JAMS pre-configured NetBeans project directories are already in the SVN repository. To open them, select File -> Open Project... and choose the projects from c:\jams\nbprojects. In order to compile a project (e.g. jams-components) right-click on the project -> Clean and Build. When doing so, the corresponding library (e.g. jams-components.jar) and all necessary libraries are created and are automatically copied into c:\jams\lib.

Models (e.g. J2000)

1. In NetBeans: File -> New Project -> Java Project with Existing Sources
2. Indicate project name (e.g. J2000) and directory (e.g. c:\nbprojects\J2000)(the compiled classes and the JAR file are stored here) -> Next
3. Source Package Folder -> Add Folder -> c:\jamsmodels\J2000\src -> OK
4. Finish import
5. Include libraries: right click on J2000/Libraries -> Add JAR/Folder... and select the JAMS libraries c:\jams\bin\jams-api.jar and c:\jams\bin\jams-main.jar. Alternatively, the corresponding projects (c:\jams\nbprojects\jams-api und c:\jams\nbprojects\jams-main) can be integrated directly with "Add Project...", but the transformation will take longer.
6. Right click on J2000 -> Clean and Build (Compile project and create J2000.jar in c:\nbprojects\J2000\dist\)

These steps are repeated for all other projects which should be installed (e.g. J2000g and JAMSComponents). There are differences according to the size of required libraries (e.g. J2000g also requires J2000). In all model projects at least the libraries jams-api.jar and jams-main.jar have to be integrated.

Template for JAMS Components

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

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

Afterwards, "JAMSComponent" can be selected file type when creating a new class.

Executing JAMS/J2000

In order to execute JAMS (JAMSLauncher or JUICE) the project jams-starter (c:\jams\nbprojects\jams-starter) is opened as main project (see check box in the project open dialog). This project does not contain any JAVA sources Dieses Projekt beinhaltet keinerlei JAVA-Quellen, aber alle zum Starten von JAMS notwendigen Bibliotheken sowie zwei Start-Konfigurationen (JAMS-Launcher und JUICE). Ein Umschalten kann über die Drop-Down-Box in der NetBeans-Toolbar erfolgen. Gestartet wird das Projekt über F6, den Start-Button in der NetBeans-Toolbar oder das Kontextmenu (Rechtsklick auf jams-starter). Die beim Start übergebenen Argumente können wie folgt angepasst werden:

1. Rechtsklick auf jams-starter -> Properties -> Run
2. unter "Arguments" eingeben: -c <vollständiger Pfad einer Konfigurationsdatei> -m <vollständiger Pfad einer Modelldefinitionsdatei>. Eine Liste der gültigen Argumente wird bei Verwendung der Argumente -h bzw. --help an der Standardausgabe angezeigt.

In der Standardkonfiguration sollte sich nach dem Start der JAMS-Launcher bzw. JUICE öffnen. Über Datei -> Modell Laden... kann nun ein Modell geladen werden.

Für die Ausführung der meisten Modelle ist darüber hinaus die Bereitstellung zusätzlicher Bibliotheken notwendig (z.B. J2000.jar und jams-components.jar). Über Extras -> Einstellungen ändern... können dazu weitere Bibliotheken angegeben werden, die dem Modell dann bei der Ausführung zur Verfügung stehen. Hierzu gehören auch alle Bibliotheken, von denen Modellkomponenten ggf. abhängig sind. Nach Beendigung des JAMS-Launchers werden die vorgenommenen Einstellungen automatisch in der Systemkonfigurationsdatei gespeichert.

Hinweis: Nach Modifikationen an Modellkomponenten muss vor der Ausführung immer erst die JAR-Datei mit den Komponenten neu erzeugt werden (Schritt 6 in "Entwicklungsumgebung einrichten/Modelle")!

Achtung:

Für die Funktionen zur 3D-Visualisierung (in den JAMS-Standardkomponenten MapCreator3D und zugehörige Klasse Styled3DMapPane bzw. im WorldWind Viewer) werden plattformabhängige Bibliotheken benötigt, die sich im Verzeichnis "c:\jams\bin" befinden. Sollen diese Funktionen genutzt werden, muss beim Start von JAMS/JUICE der entsprechende Pfad mit dem Parameter "-Djava.library.path=[Pfad]" angegeben werden. Dazu wird der Eigenschaftsdialog von jams-starter geöffnet (Rechtsklick -> Properties) und unter Run der entsprechende Wert im Feld VM Options eingetragen.

Ein entsprechender Kommandozeilenaufruf von JAMS für 64-bit Windows-Systeme könnte daher lauten:

java -jar juice-starter.jar -Djava.library.path=c:/jams/bin/win64