Brief instruction JAMS development
Contents |
Introduction
The following instruction describes the instalment 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
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
- Tortoise SVN (http://tortoisesvn.tigris.org)
- 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 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.
- Verzeichnis für JAMS anlegen (als Beispiel wird im Folgenden c:\jams verwendet)
- Verzeichnis für Modelle anlegen (als Beispiel wird im Folgenden c:\jamsmodels verwendet)
- Verzeichnis für Modelldaten anlegen (als Beispiel wird im Folgenden c:\jamsmodeldata verwendet)
- Rechtsklick auf c:\jams -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jams/trunk als Repository-URL angeben -> OK
- Rechtsklick auf c:\jamsmodels -> SVN Checkout und http://svn.geogr.uni-jena.de/svn/jamsmodels/trunk als Repository-URL angeben -> OK
- Rechtsklick 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 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:
- Kommandozeile im Verzeichnis c:\jams\build öffnen,
- den Befehl "ant clean" zum Löschen vorhandener JAMS-Bibliotheken aufrufen,
- 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 Rechtsklick 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\lib kopiert.
Modelle (z.B. J2000)
- In NetBeans: File -> New Projekt -> Java Project with Existing Sources
- Projektname (z.B. J2000) und Verzeichnis (z.B. c:\nbprojects\J2000) vergeben (hier landen die compilierten Klassen und das JAR-File) -> Next
- Source Package Folder -> Add Folder -> c:\jamsmodels\J2000\src -> OK
- Import beenden
- Bibliotheken einbinden: Rechtsklick auf J2000/Libraries -> Add JAR/Folder... und hier die JAMS-Bibliotheken c:\jams\bin\jams-api.jar und c:\jams\bin\jams-main.jar auswählen. Alternativ können auch direkt die zugehörigen Projekte (c:\jams\nbprojects\jams-api und c:\jams\nbprojects\jams-main) mittels "Add Project..." eingebunden werden, allerdings dauert der Übersetzungsvorgang dann länger.
- Rechtsklick auf J2000 -> Clean and Build (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 Modell-Projekte müssen mindestens die Bibliotheken jams-api.jar und jams-main.jar eingebunden werden.
Template für JAMS-Komponenten
Ein Komponenten-Template für NetBeans ist unter c:\jams\JAMSmain\JAMSComponent.java zu finden (ggf. vorher anpassen!). Die Einbindung in NetBeans erfolgt wie folgt:
- Tools -> Templates -> Java -> Add...
- 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:
- Rechtsklick auf jams-starter -> Properties -> Run
- 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
