Kurzanleitung JAMS-Entwicklung

Aktuelle Version vom 11. Juni 2012, 12:06 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 benötigter Software

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

Arbeitsverzeichnis vorbereiten

Quellen herunterladen

Sämtliche JAVA-Quellen und Scripte für JAMS und seine Modelle 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 JAMS-SVN zuzugreifen, wird ein gültiger SVN-Account benötigt. Zum rein lesenden Zugriff kann der Account "guest" mit Passwort "guest" verwendet werden. 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. Rechtsklick auf c:\jams -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jams/trunk als Repository-URL angeben -> OK
4. Rechtsklick auf c:\jamsmodels -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jamsmodels/trunk als Repository-URL angeben -> OK

Downloading 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 be downloaded here.

1. Verzeichnis für Modelldaten anlegen (als Beispiel wird im Folgenden c:\jamsmodeldata verwendet)
2. Rechtsklick auf c:\jamsmodeldata -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/modeldata als Repository-URL angeben, aber noch nicht bestätigen
3. Browse button (rechts vom Repository-Eingabefeld) verwenden, um gewünschte Datenverzeichnisse zu wählen (Mehrfachauswahl bei gleichzeitigem Halten von CTRL möglich) -> OK

Verzeichnisstruktur

Als Ergebnis des letzten Schrittes liegen 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 JAMS ohne Netbeans compiliert werden kann. Darüber hinaus befinden sich im nbprojects Unterverzeichnis bereits vorkonfigurierte NetBeans-Projekte, die ein leichtes Einrichten einer JAMS-Entwicklungsumgebung ermöglichen.

Das Modellverzeichnis beinhaltet Unterverzeichnisse mit den JAVA-Quellen verschiedener Modellbibliotheken, welche die zur Erstellung von JAMS-Modellen notwendigen Modellkomponenten beinhalten. Auch dieses Verzeichnis beinhaltet ein nbprojects Unterverzeichnis mit bereits vorkonfigurierten NetBeans-Projekten

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

JAMS und Modelle compilieren

JAMS-Binärpakete

Eine Erzeugung neuer JAMS-Bibliotheken ist nicht zwingend erforderlich, da das JAMS SVN-Repository jeweils eine aktuelle Version aller benötigten Bibliotheken beinhaltet (Verzeichnis c:\jams\lib). Die Einrichtung einer JAMS-Entwicklungsumgebung und das Übersetzen von JAMS-Bibliotheken ist daher nur dann notwendig, wenn JAMS oder seine Standardkomponenten modifiziert oder debuggt werden sollen. Sollen aussschliesslich Komponenten von JAMS-Modellen bearbeitet werden, so ist im Abschnitt Modelle fortzufahren.

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\lib mit Bibliotheken gefüllt, welche alle benötigten Systemklassen sowie verschiedene Standard-Modellkomponenten beinhalten. Gemeinsam mit den Fremdbibliotheken in c:\jams\ext stellen sie die JAMS-API, die Laufzeitumgebung sowie verschiedene grafische Benutzeroberflä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 mit File -> Open Project... das Projekt "jams-starter" unter c:\jams\nbprojects auswählen, die Option "Open Required Projects" wählen und das Projekt öffnen. Zum Compilieren von JAMS einfach Rechtsklick auf "jams-starter" -> Clean and Build. Dabei werden alle benötigten Bibliotheken erzeugt und automatisch nach c:\jams\lib kopiert.

Modelle (z.B. J2000)

Für J2000, J2000-S und J2000g sind ebenfalls vorkonfigurierte NetBeans-Projekte im SVN-Repository enthalten. Zum Öffnen in NetBeans mit File -> Open Project... das geünschte Modell-Projekt unter c:\jamsmodels\nbprojects auswählen, die Option "Open Required Projects" wählen und das Projekt öffnen. Falls der "Reference Problems" Dialog erscheint, wird nach Betätigen des "Resolve Problems..." Buttons der Speicherort der Projekte "jams-api" und "jams-main" im JAMS Projektverzeichnis (z.B. c:\jams\nbprojects) ausgewählt. Nach dem Compilieren des Projekts werden alle benötigten Bibliotheken automatisch im "dist" Unerverzeichnis innerhalb des Projektverzeichnisses gespeichert.

Für andere Modelle ohne vorkonfigurierte NetBeans-Projekte müssen die folgenden Schritte durchgeführt werden:

1. In NetBeans: 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: Rechtsklick auf J2000/Libraries -> Add JAR/Folder... und hier die JAMS-Bibliotheken jams-api.jar und jams-main.jar im Verzeichnis c:\jams\lib\lib auswählen.
6. Rechtsklick auf J2000 -> Clean and Build (Projekt compilieren und J2000.jar in c:\nbprojects\J2000\dist erzeugen)

Template für JAMS-Komponenten

Ein Komponenten-Template für NetBeans ist unter c:\jams\template\JAMSComponent.java zu finden (ggf. vorher anpassen!). Die Einbindung in NetBeans erfolgt wie folgt:

1. Tools -> Templates -> Java -> Add...
2. Oben genanannte Datei auswählen -> Add

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

JAMS/J2000 ausführen

Zur Ausführung von JAMS (JAMSLauncher oder JUICE) wird das Projekt jams-starter (c:\jams\nbprojects\jams-starter) als Main-Projekt geöffnet (siehe Checkbox im Projekt-Open-Dialog). 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 Bearbeiten -> Einstellungen ändern... können dazu in JAMS 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