Kurzanleitung JAMS-Entwicklung

Version vom 1. Oktober 2009, 16:32 Uhr

Einleitung

Die folgende Anleitung beschreibt die Einrichtung einer JAMS/J2000-Entwicklungsumgebung mit Tortoise (SVN-Client) und NetBeans (Java-IDE). Selbstverständlich kann auch alternative Software eingesetzt werden.

Diese Anleitung ist gedacht für Anwender, die JAMS erweitern neue Komponenten entwickeln oder einfach nur wissen wollen, was genau in JAMS und/oder den Prozesskomponenten passiert. Weiterhin kann das Aufsetzen der Entwicklungsumgebung dabei helfen, Fehlerquellen aufzufinden und zu beheben.

Installation der benötigter Software

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

Verzeichnisse einrichten

Daten herunterladen

Sämtliche JAVA-Quellen und Scripte für JAMS und seine Modelle sowie eine Reihe von Modelldatensätzen werden in einem Subversion(SVN)-Repository [1] verwaltet. Bei Subversion handelt es sich um eine Software zur Versionsverwaltung von Dateien und Verzeichnissen [2]. Um auf das JAMS-SVN zuzugreifen, wird ein gültiger SVN-Account benötigt. Zum Einrichten einer JAMS-Arbeitsumgebung werden zunächst die benötigten Verzeichnisse angelegt und mit Daten aus dem SVN-Repository gefüllt.

1. Verzeichnis für JAMS anlegen (als Beispiel wird im Folgenden c:\jams verwendet)
2. Verzeichnis für Modelle anlegen (als Beispiel wird im Folgenden c:\jamsmodels verwendet)
3. Verzeichnis für Modelldaten anlegen (als Beispiel wird im Folgenden c:\jamsmodeldata verwendet)
4. rechte Mousetaste auf c:\jams -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jams/trunk als Repository-URL angeben -> OK
5. rechte Mousetaste auf c:\jamsmodels -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jamsmodels/trunk als Repository-URL angeben -> OK
6. rechte Mousetaste auf c:\jamsmodeldata -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/modeldata als Repository-URL angeben -> OK

Verzeichnisstruktur

Als Ergebnis des letzten Schrittes liegen drei Verzeichnisse für JAMS, JAMS-Modelle und Modelldaten vor.

Das JAMS-Verzeichnis beinhaltet neben den JAVA-Quellen sowohl JAMS-Binärdateien als auch einige Ant-Scripte [3], mit denen diese erzeugt werden können. Darüber hinaus befinden sich in dem Verzeichnis bereits vorkonfigurierte NetBeans-Projekte, die ein leichtes Einrichten einer JAMS-Entwicklungsumgebung ermöglichen sollen.

Das Modellverzeichnis beinhaltet Unterverzeichnisse mit den JAVA-Quellen verschiedener Modellbibliotheken, welche die zur Erstellung von JAMS-Modellen notwendigen Modellkomponenten beinhalten.

Das Datenverzeichnis beinhaltet Modelldefinitionen und Eingangsdaten für verschiedene Modellanwendungen.

JAMS compilieren

Ant-Scripte

Um eine aktuelle Version der JAMS-Bibliotheken zu erzeugen, ist die Einrichtung einer Entwicklungsumgebung nicht zwingend erforderlich. Hierfür kann alternativ ein Ant-Script unter c:\jams\build\build.xml verwendet werden, welches zentral die Übersetzung und Zusammenstellung aller benötigten Ressourcen durchführt. Voraussetzung ist dafür die Installation von Apache Ant, welches von http://ant.apache.org/bindownload.cgi heruntergeladen werden kann.

Zur Erzeugung der JAMS-Bibliotheken mit Ant ist wie folgt vorzugehen:

1. Kommandozeile im Verzeichnis c:\jams\build öffnen,
2. den Befehl "ant clean" zum Löschen vorhandener JAMS-Bibliotheken aufrufen,
3. den Befehl "ant" zum Erzeugen aller JAMS-Bibliotheken aufrufen.

Diese Schritte können auch durch Ausführen einer Batch-Datei unter c:\jams\build\build.bat durchgeführt werden. Im Ergebnis wird das Verzeichnis c:\jams\bin mit JAMS-Bibliotheken gefüllt, welche alle benötigten Systemklassen sowie verschiedene Standard-Modellkomponenten beinhalten. Gemeinsam mit den Fremdbibliotheken in c:\jams\lib stellen sie die JAMS-API, die Laufzeitumgebung sowie verschiedene grafische Oberflächen zum Erstellen und Ausführen von Modellen oder Auswerten von Modellergebnissen zur Verfügung.

Entwicklungsumgebung einrichten

JAMS

Für JAMS sind bereits vorkonfigurierte NetBeans-Projektverzeichnisse im SVN-Repository enthalten. Zum Öffnen in NetBeans einfach File -> Open Project... wählen und die gewünschten Projekte unter c:\jams\nbprojects auswählen und öffnen. Zum Compilieren eines Projektes (z.B. jams-components) einfach rechte Mousetaste auf das Projekt -> Clean and Build. Dabei wird die entsprechende Bibliothek (z.B. jams-components.jar) und alle dafür notwendigen Bibliotheken erzeugt und automatisch nach c:\jams\bin kopiert.

Modelle (z.B. J2000)

1. File -> New Projekt -> Java Project with Existing Sources
2. Projektname (z.B. J2000) und Verzeichnis (z.B. c:\nbprojects\J2000) vergeben (hier landen die compilierten Klassen und das JAR-File) -> Next
3. Source Package Folder -> Add Folder -> c:\jamsmodels\J2000\src -> OK
4. Import beenden
5. Bibliotheken einbinden: rechte Mousetaste auf Libraries -> Add Project und hier JAMS aus der Liste der verfügbaren Projekte hinzufügen
6. rechte Mousetaste auf J2000 -> Clean and Build Project (Projekt compilieren und J2000.jar in c:\nbprojects\J2000\dist\ erzeugen)

Diese Schritte werden für alle weiteren aufzusetzenden Projekte (z.B. J2000g und JAMSComponents) entsprechend wiederholt. Unterschiede gibt es jeweils im Umfang der benötigten Bibliotheken (J2000g benötigt z.B. auch J2000). In alle JAMS-Projekte muss generell wie bei J2000 das Projekt JAMS (oder die Bibliothek JAMS.jar, z.B. aus dem Verzeichnis c:\nbprojects\JAMS\dist) eingebunden werden. Weitere Bibliotheken, welche von JAMSComponents benötigt werden, befinden sich im lib-Verzeichnis des JAMS-Repositories (z.B. c:\jams\lib).

Achtung:

In JAMSComponents befindet sich auch eine 3D-Visualisierungkomponente (MapCreator3D und zugehörige Klasse Styled3DMapPane), welche plattformabhängige Bibliotheken benötigt, die sich nicht im o.g. lib-Verzeichnis befinden. Um diese Komponente übersetzen und nutzen zu können, muss zuvor Java3D für die entsprechende Plattform installiert werden. Eine Installationsdatei für Windows befindet sich im Rootverzeichnis des JAMS-Repositories (z.B. c:\jams) und heisst java3d-1_5_0-windows-i586.exe. Andere Versionen können unter http://java.sun.com/javase/technologies/desktop/java3d heruntergeladen werden.

Template für JAMS-Komponenten

Ein Komponenten-Template für NetBeans ist im JAMS-Verzeichnis des JAMS-Repositories (z.B. c:\jams\JAMS\JAMSComponent.java) zu finden (ggf. vorher anpassen!). Die Einbindung in NetBeans erfolgt wie folgt:

1. Tools -> Template Manager -> Java Classes -> Add...
2. Add.. und oben genanannte Datei auswählen

Danach kann beim Anlegen einer neuen Klasse "JAMSComponent" als File Type ausgewählt werden.

JAMS/J2000 ausführen

Für die JAMS-Ausführung wird dann wie folgt vorgegangen:

1. zur einfacheren Ausführung rechte Mousetaste auf JAMS -> Set Main Project
2. rechte Mousetaste auf JAMS -> Properties -> Run und
   • "Main Class" auf jams.JAMS setzen
   • Unter "Arguments" eingeben: -c <vollständiger Pfad einer Konfigurationsdatei> -m <vollständiger Pfad einer Modelldefinitionsdatei>. Beide Argumente sind optional und können auch über die grafische Oberfläche des JAMS-Launchers ausgewählt werden.
3. rechte Mousetaste auf JAMS -> Run Project oder einfach Taste F6

In der Standardkonfiguration sollte sich nun der JAMS-Launcher öffnen. Über File -> Load Model Configuration kann nun eine Modelldefinitionsdatei 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 JAMSComponents.jar). Über Edit -> Edit Options können dazu weitere Bibliotheken angegeben werden, die dem Modell dann bei der Ausführung zur Verfügung stehen. Nach Beendigung des JAMS-Launchers werden die vorgenommenen Einstellungen in der Systemkonfigurationsdatei gespeichert.

Hinweis: Nach Modifikationen an Modellkomponenten muss vor der Ausführung immer erst das JAR-File mit den Komponenten neu erzeugt werden (jeweils Schritt 6 in "NetBeans-Projekte aufsetzen")!