Lösungen

Java Remote Debugger

15.11.2006 von Elmar Fuchs

Der Domino-Designer ermöglicht die Erstellung von Java-Programmcode für Agenten und Skriptbibliotheken. Er bietet aber keine Unterstützung bei der Fehlersuche mittels eines Java- Debuggers. In der Version 7 wird jedoch das Remote Debugging von Java-Agenten unterstützt. Debugger externer IDEs können damit zur Fehlersuche verwendet werden.

Bereits seit der Version 4.5 von Lotus Notes Domino ist die Programmierung von Java in Notes möglich. Die zuerst angebotene Möglichkeit, Agenten in dieser Programmiersprache zu erstellen, wurde mit der Version 6 um die Java-Skriptbibliotheken erweitert. Dazu kommen die Integrationsmöglichkeiten für Applets sowie seit der Version 7 die in Java programmierbaren Web Services.

Die Java-Entwicklungsumgebung ist jedoch auch in der Version 7 immer noch eher spartanisch zu nennen. Die in der Version 6 eingeführte automatische Codeergänzung unterstützt nur die Formelsprache und LotusScript. Für das Refactoring, die Verbesserung der internen Struktur des Programmcodes (zum Beispiel: Änderung von Symbolnamen, Verschieben einer Methode in eine andere Klasse, Aufteilung eines Moduls) bei Beibehaltung des externen Verhaltens, sind keine Werkzeuge vorhanden. Eine Versionsverwaltung und ein Debugger fehlen ebenfalls.

Vorgehensweise

So spricht einiges dafür, den in Domino benötigten Java-Programmcode in einer anderen IDE (Integrated Development Environment, integrierte Entwicklungsumgebung) zu entwickeln, welche diese Merkmale besitzt. Unterstützt die IDE die Java Platform Debugger Architecture (JDPA, siehe java.sun.com/products/jpda) können Sie den Programmcode auch im Kontext der Notes-Anwendung debuggen. Möglich ist dies unter anderem mit den IDEs Eclipse und Rational Application Developer.

Der Artikel beschreibt die für das Remote Debugging von Java-Agenten notwendigen Schritte am Beispiel von Eclipse. Daneben wird kurz die generelle Vorgehensweise zur Erstellung von Java-Programmcode für Notes Domino in einer externen IDE demonstriert.

Zu beachten ist der Unterschied in der Anwendung des Begriffs „remote“ im Zusammenhang mit dem Debugging von Agenten. In der Ausgabe 10/06 von Expert´s inside Lotus/Notes Domino haben wir Sie im Artikel „Der Lotus-Script Remote Debugger“ mit der Möglichkeit des Remote Debugging von serverbasierten LotusScript-Agenten vertraut gemacht. In diesem Zusammenhang steht der Begriff „remote“ für den entfernten Zugriff mit dem Notes-Client auf einen LotusScript-Agenten, der auf dem Server läuft. Im Gegensatz dazu steht beim Debuggen von Java-Programmcode im Notes-Client der Begriff für den Zugriff der externen IDE auf die JVM (Java Virtual Machine) des Notes-Clients.

Rückblick

In der Version 6 war das Remote Debugging von Java-Agenten mittels einer externen IDE ebenfalls schon möglich (ab Version 6.0.3), wurde jedoch nicht offiziell unterstützt. Die Schritte in der externen IDE entsprachen dabei den hier im Weiteren vorgestellten. Die Debugeinstellungen mussten jedoch den Port 9788 verwenden. Außerdem war zu beachten, dass sich die Datei NOTES.JAR direkt im Programmverzeichnis von Notes befindet und Notes Domino 6 noch das JDK 1.3.1 verwendet. Auf Seiten des Notes-Clients erfolgte die Aktivierung über eine Einstellung in der Datei notes.ini. In dieser musste die Zeile

JavaEnableDebug=1

ergänzt werden. Informationen zum Remote Debugging von Java-Agenten in der Version 6 finden Sie im Bereich developerworks der IBM-Webseiten unter der Adresse www-128.ibm.com/developerworks/lotus/library/notes-eclipse.

Das Testszenario

Als Testsystem verwenden wir einen Lotus Notes Client 7.0 und als IDE Eclipse 3.1 mit der Java-Version 1.4.1_07. Die Datenbank besteht lediglich aus einer Maske mit zwei Feldern (ein Textfeld, ein Feld zur Speicherung der Uhrzeit), einer Ansicht zur Anzeige der Dokumente und einem Agenten, dessen Erstellung im Folgenden beschrieben wird. Dieser wird in Java programmiert und führt einige einfache Aktionen aus. Auf eine Fehlerbehandlung wird verzichtet. Zur Ausführung des Agenten stehen einige Testdokumente zur Verfügung.

Die Programmierung des Agent kann sowohl im Domino-Designer als auch in Eclipse erfolgen. Erstellen Sie den Agent im Domino-Designer, muss der Programmcode anschließend in ein Java-Projekt in Eclipse eingefügt werden, um das Remote Debugging durchzuführen. Verwenden Sie Eclipse als Entwicklungsumgebung für den Programmcode, erstellen Sie im Nachgang den eigentlichen Agent unter Verwendung der fertigen Java-Klasse. Aus den bereits genannten Gründen ist dieser zweite Weg der empfehlenswerte, den wir im Folgenden auch gehen.

Agentenprogrammierung in Eclipse

Als Erstes benötigen wir ein neues Java-Projekt. Erstellen Sie dieses über den Menüpunkt File /New / Project. Um die Notes-Klassen verwenden zu können, müssen Sie die Datei NOTES.JAR als Bibliothek zum Projekt hinzufügen. Klicken Sie dazu im Fenster Project Explorer auf den Namen des Projekts, und wählen Sie den Menüpunkt Project/Properties. Unter dem Eintrag Java Build Path fügen Sie auf dem Register Libraries mit der Schaltfläche Add External JARs den benötigten Eintrag hinzu. Die Datei NOTES.JAR finden Sie im Verzeichnis ..lotus\notes\jvmib\ext (Bild 1).

Bild 1: Der Zugriff auf die erforderliche .jar-Datei.

Bild 2: Die Erstellung der Java-Klasse.

Java-Projekte sind in sogenannten Packages organisiert. Erstellen Sie über File/New/Package ein neues Package in Ihrem Projekt, um dieser allgemeinen Designanforderung einer Java-Anwendung zu genügen. Anschließend können wir die eigentliche Klasse über File / New / Class erzeugen (Bild 2). Im Dialogfenster New Java Class müssen Sie lediglich den Namen und die Superklasse der neuen Klasse bestimmen. Der Packagename wird aus dem Projekt übernommen. Für alle anderen Einstellungen können Sie die Standardwerte verwenden. Die Superklasse eines Lotus Notes-Agenten ist immer lotus.domino.AgentBase. Nach der Eingabe von lotus. können Sie mittels der Tastenkombination [Strg]+[Leertaste] die Codeergänzung verwenden. Werden die benötigten Klassen angezeigt, ist dies gleichzeitig ein Hinweis, dass das Einbinden der Datei NOTES.JAR funktioniert hat.

Nachteil der Programmierung

Ein Nachteil der Programmierung des Agenten in einer externen IDE ist der Umstand, dass das immer gleiche Grundgerüst des Programmcodes nicht automatisch vorhanden ist. Um den Text nicht manuell erfassen zu müssen, bietet es sich an, im Domino-Designer einen neuen Java-Agent zu erstellen und die Programmzeilen in die neue Klasse zu kopieren.

Der in Listing 1 dargestellte Agent führt einige Aktionen aus, die jedoch nur der Möglichkeit dienen, den Ablauf des Agenten im Debugger zu verfolgen. Zuerst wird eine Schleife durchlaufen, die es uns ermöglicht, nach dem Start des Agenten diesen im Eclipse Debugger aufzufangen [1]. Anschließend wird der aktuelle Benutzer auf der Java Debug-Konsole ausgegeben [2] und auf das aktuell ausgewählte Dokument zugegriffen [3]. Unter Verwendung eines Objekts der Klasse DateTime wird die aktuelle Zeit in das Dokument geschrieben [4] und zum Abschluss das Dokument gespeichert [5].

Mit der Speicherung des Programmcodes wird gleichzeitig die benötigte Datei vom Typ *.class erstellt, welche in unseren eigentlichen Domino-Agent eingebunden wird.

package com.elfu.NotesJava.Agents; import lotus.domino.*; public class JavaAgent1 extends AgentBase { public void NotesMain() { Document doc; try { Session session = getSession(); AgentContext agentContext = session.getAgentContext(); for (int i = 0; i < 100; i++) [1] { Thread.sleep(200); } String user = session.getCommonUserName(); [2] System.out.println("Aktueller Benutzer ist " + user); doc = agentContext.getDocumentContext(); [3] DateTime dt = session.createDateTime("Today"); [4] dt.setNow(); doc.replaceItemValue("AgentStartzeit", dt.getLocalTime()); doc.save(true, false); [5] } catch(Exception e) { e.printStackTrace(); } } }

Erstellung des Agenten

Den Agent erstellen Sie wie gewohnt im Domino-Designer. Als Auslöser verwenden Sie On event/Action menu selection, als Ziel All selected documents.

Um eine externe Klasse in einem Java-Agent in Notes Domino zu verwenden, stehen Ihnen vier Möglichkeiten zur Auswahl:

Die Klasse direkt in den Agenten importieren.
Die Klasse in eine Skriptbibliothek einfügen und diese in dem Agenten verwenden.
Über den NOTES.INI-Parameter JavaUser-Classes den Zugriff auf die Klasse steuern.
Die Klasse in das Verzeichnis ..otus\notes\jvmib\ext kopieren.

Die ersten beiden Varianten bieten den Vorteil, dass die Klasse Bestandteil der Datenbank ist und somit repliziert wird. Sie steht also in allen Repliken zur Verfügung. Nachteilig ist dabei, dass Sie die Klasse nur in der speziellen Datenbank nutzen können. Soll sie in weiteren Datenbanken verwendet werden, muss sie in diese ebenfalls importiert werden. Dies erfordert bei nachträglichen Codeänderungen eine sehr aufmerksame Arbeitsweise.

Bei der dritten und vierten Variante liegt die Java-Klasse außerhalb der Notes-Datenbank und muss deshalb nicht nach jeder Änderung neu importiert werden. Sie wird jedoch auch nicht mit repliziert, sodass sie auf jeden Computer verteilt werden muss, auf welchem der Agent laufen soll. Im Falle der Steuerung über den NOTES.INI Parameter muss auch diese Änderung in der Konfigurationsdatei der Server und Clients vorgenommen werden.

Bild 3: Der Import der Java-Datei.

In unserem Beispiel wollen wir den Standardweg über den Import in den Agenten verwenden. Wählen Sie dazu unter Action den Eintrag Imported Java. Über die Schaltfläche Import Class Files binden Sie die in Eclipse erstellte Datei .class in den Agenten ein. Haben Sie die Standardeinstellungen verwendet, finden Sie die Datei unterhalb des für Eclipse festgelegten Workspace im Verzeichnis <Projektname>\bin\<PackageName> (Bild 3).

Notes-Client einrichten

Das Remote Debugging eines Java-Agenten erfolgt auf dem Notes-Client unter Steuerung von dessen JVM. Dabei werden drei verschiedene Varianten unterschieden:

Der Java-Code läuft im Vordergrund. Dies erfolgt zum Beispiel nach einem Aufruf eines Agenten über den Menüpunkt Action / <NameDesAgenten>.
Der Java-Code läuft im Hintergrund. Dies trifft beispielsweise auf lokale periodische Java-Agenten zu.
Der Java-Code wird über die Webvorschau des Domino-Designers ausgeführt. Dabei kann es sich zum Beispiel um ein Java-Applet in einer Maske handeln.

Für jede dieser Situationen muss das Remote Debugging separat frei geschaltet werden. Gleichzeitig legen Sie dabei den Port fest, über welchen der externe Debugger der IDE auf die JVM zugreift.

Für die Konfiguration wählen Sie File / Tools / Java Debugging Preferences (Bild 4). Nach Änderungen für im Vorder- oder Hintergrund ausgeführten Java-Code müssen Sie den Notes-Client neu starten. Betreffen die Einstellungen die Webvorschau, reicht es aus, diese erneut zu starten. Die Einstellungen bewirken das Setzen einiger Variablen in der Konfigurationsdatei notes.ini (Tabelle 1). Mit der erstmaligen Einrichtung werden diese Variablen in die Datei notes.ini eingefügt. Wird das Debugging wieder deaktiviert, bleiben die Variablen erhalten. Als Wert für die jeweilige Option wird lediglich 0 gesetzt.

Bild 4: Die Festlegung der Präferenzen für das Debugging von Java.

Tabelle 1: Die Parameter für die notes.ini.
Parameter	Bedeutung
JavaDebugClientForeground	Der Parameter steuert das Remote Debugging von im Vordergrund laufendem Java-Code. Mögliche Werte sind 1 (aktiviert) oder 0 (deaktiviert).
JavaDebugClientScheduled	Analog zu JavaDebugClientForeground, jedoch für im Hintergrund laufenden Java-Code.
JavaDebugClientWebPreview	Analog zu JavaDebugClientForeground, jedoch für in der Webvorschau laufenden Java-Code.
JavaDebugClientForegroundPort	Der Parameter beinhaltet den Port, auf dem die JVM den Zugriff für das Debuggen von im Vordergrund laufenden Java-Programmcode ermöglicht. Als Standard wird der Port 8701 verwendet.
JavaDebugClientScheduledPort	Der Parameter legt den Port für im Hintergrund laufenden Java-Code fest. Der Standardport ist hier 8702.
JavaDebugClientWebPreviewPort	Für Java-Programmcode in der Webvorschau wird mit diesem Parameter der Port festgelegt. Der Standardport ist 8703.

Beachten Sie folgende Punkte:

Der in der Hilfe gegebene Hinweis, in den Sicherheitseinstellungen des Agenten, des Web Service oder der Skriptbibliothek die Eigenschaft Compile Java Code with debugging information zu aktivieren, betrifft nur Java-Programmcode, den Sie direkt im Domino-Designer programmieren und zum Debuggen anschließend in eine externe IDE exportieren.
Ein Debuggen auf dem Server ist nicht möglich.
Da das Debugging die Performance belastet, sollten Sie es deaktivieren, wenn es nicht benötigt wird.
Die Übertragung der Daten über das Netzwerk erfolgt ungesichert.

Debugging durchführen

Nach der erfolgreichen Einrichtung können Sie das Remote Debugging durchführen. Starten Sie im Notes-Client den Java-Programmcode. In unserem Beispiel ist dies der Agent in der Testdatenbank. Durch die am Anfang des Agenten eingebaute Zeitschleife können Sie den Agent einfangen und testen.

Öffnen Sie dazu in Eclipse im Java-Projekt die erstellte Klasse. Über den Menüpunkt Run / Debug konfigurieren Sie den Zugriff auf die JVM des Notes-Clients (Bild 5). Verwenden Sie den Projektnamen sowie die im Notes-Client festgelegte Portnummer. Erfolgt der Zugriff nicht lokal, sondern befinden sich der Notes-Client und die IDE auf unterschiedlichen Computern, müssen Sie zusätzlich die Hostadresse des Notes-Clients angeben. Andernfalls verwenden Sie die Standardeinstellung localhost. Über die Schaltfläche Debug stellen Sie die Verbindung zur JVM her. Wechseln Sie anschließend in die Debug-Perspektive, und wählen Sie den Thread des Agenten (Bild 6). Über die einzelnen Schaltflächen der Debuggersymbolleiste steuern Sie das Debugging. Ausgewählte Kommandos enthält Tabelle 2.

Bild 5: Die Konfiguration des Zugriffs auf die JVM von Lotus Notes/Domino.

Bild 6: Die Debug-Perspektive mit dem Thread des Agenten.

Entdecken Sie bei der Ausführung Fehler, müssen Sie nach der Änderung des Programmcodes diesen neu in den Notes Domino-Agenten importieren. Das sogenannte „hot code replace“, die direkte Codeänderung wird von der Notes JVM nicht unterstützt (Bild 7).

Bild 7: Eine Fehlermeldung beim Versuch der Ersetzung von Code während des Debug-Vorgangs.

Tabelle 2: Die wichtigsten Funktionen in der Symbolleiste des Java Remote Debugger.
Symbol	Bezeichnung	Bedeutung
1	Resume	Das Kommando setzt die Ausführung des Programms fort.
2	Suspend	Mit diesem Kommando wird die Ausführung des Programms unterbrochen.
3	Terminate	Das Kommando beendet das ausgewählte Debuggerziel.
4	Disconnect	Über dieses Kommando wird die Verbindung zwischen Debugger und der externen Anwendung getrennt.
5	Step Into	Mit dem Befehl wird das Programm schrittweise durchlaufen.
6	Step Over	Durch dieses Kommando wird die aktuelle Befehlszeile übersprungen.
7	Run to Return	Mit diesem Befehl wird die aktuelle Methode verlassen.

Zusammenfassung

Zusammenfassend lässt sich feststellen, dass die Vorteile der Verwendung einer externen IDE gegenüber dem Domino-Designer bei der Java-Programmierung die Ausführung einiger zusätzlich notwendiger Schritte durchaus gerechtfertigt erscheinen lassen. Dazu kommt, dass Eclipse die Basis für die neue Clientgeneration von IBM ist. So basieren sowohl der neue Sametime Connect Client als auch der zukünftige Notes-Client (Codename Hannover) auf Eclipse. Die Beschäftigung mit Eclipse ist somit nicht nur in Hinsicht auf das Remote Debugging von Java-Anwendungen in Notes Domino von Vorteil.