Die Java-API im Workplace Designer

Wir haben uns in den vergangenen Ausgaben von Expert´s Inside Lotus Notes/Domino (ab Heft 1/2006) bereits mit verschiedenen Aspekten der Anwendungsentwicklung mit dem Workplace Designer beschäftigt. Nach einem Überblick über die Grundlagen waren Themen wie Zugriffssteuerung auf Dokumente und Anwendungen, Erstellung von Antwortdokumenten und dynamischen Tabellen Gegenstand der einzelnen Artikel. Dabei wurde deutlich, dass der Workplace Designer ein leistungsstarkes Werkzeug ist, welches umfangreiche Möglichkeiten zur Erstellung von Komponenten für den Workplace Portalserver bietet. Eine wesentliche Rolle spielt dabei JavaScript als unterstützte Programmiersprache der Entwicklungsumgebung.

Möglichkeiten des Workplace Designer

Die gezeigten Möglichkeiten des Workplace Designer lassen sich mit der Integration von Java- Programmcode noch erweitern. Diese Java- Integration wird durch die in der JavaScript-Engine des Workplace Designer enthaltene Java-Brücke gestattet. Diese ermöglicht den Aufruf von Java direkt aus dem JavaScript-Programmcode heraus. Bereits im Workplace Designer stehen einige Java-Klassen zur Verfügung. Als Beispiel sei die Klasse XSPUrl genannt, auf die bereits in einem der vorigen Artikel Bezug genommen wurde. Sie ermöglicht die Erstellung eines URLs zum Aufruf eines neuen oder vorhandenen Dokuments. Die globalen Objekte des Workplace Designer – Content, Database, Document, PageData, Session und SessionData – sind ebenfalls in Java implementiert. Sie können im JavaScript-Editor verwendet werden und besitzen einen Eintrag in der Sprachreferenz.

Neben der Verwendung der internen Java- Klassen besteht die Möglichkeit, externe Klassen aufzurufen. Dies kommt in zwei verschiedenen Fällen in Betracht:

• Sie wollen die Klassen einer Java-API eines bestimmten Produkts verwenden, um in Ihrer Komponente eine Verbindung zu diesem Produkt herzustellen. Beispiele dafür sind die Verwendung der Workplace Collaboration Services API für die Verwendung der Workplace Messaging- Komponenten oder die Verwendung der Domino- Klassen zur Erstellung einer Schnittstelle zum Domino-Server.

• Sie besitzen fertige Java-Klassen zur Realisierung bestimmter Geschäftsprozesse und Aufgabenstellungen. Im Rahmen Ihrer Workplace- Komponente benötigen Sie genau diese Funktionalität. Die Einbindung der Java-Klassen entspricht dem Paradigma der Wieder-/ Mehrfachverwendung von Software und ist wesentlich effektiver als eine Neuentwicklung im Workplace Designer.
  

Die Workplace Collaboration Service APIeinbinden

Die Workplace-API wird mit dem Workplace Collaboration Server installiert. Ihre Klassen können direkt aus dem JavaScript-Programmcode heraus aufgerufen werden. Voraussetzung ist, dass der jeweilige Service auf dem Server aktiv ist. Wollen Sie eine E-Mail per Programmcode erstellen, muss auf dem Workplace Server der Mailservice unterstützt werden (im Regelfall ist dies Mail_Server_1). Listing 1 enthält den Programmcode zur Erstellung eines Kalendereintrags über die Workplace Collaboration Services API. Weitere Informationen zur Workplace Collaboration Service API finden Sie unter dem Begriff „IBM Workplace Software Development Kit“ im Internet auf der Seite www.lotus.com/ldd/lwpapi.

Da der Workplace Services Express Server keine eigenen Komponenten für Mail und Kalender besitzt, wird für die Verwendung der Workplace- API ein Workplace Collaboration Server benötigt. Nutzen Sie die Express-Version, müssen Sie den Weg über die API des verwendeten E-Mail-Programms wählen, vorausgesetzt, dieses stellt eine Java-API zur Verfügung. Weiter unten im Artikel betrachten wir den Aufruf der Domino-Klassen aus dem JavaScript-Code des Workplace Designer.

Eigene Java-Klassen verwenden

In vielen Unternehmen existieren heute bereits Bibliotheken mit einer großen Anzahl von Java- Klassen zur Realisierung der unterschiedlichsten Aufgaben. Häufig soll im Rahmen der Komponentenentwicklung mit dem Workplace Designer auf diese zurückgegriffen werden.

Wenn Sie die benötigten Klassen auf den Workplace Server kopieren und den Server so einrichten, dass er sie erkennt, können Sie die Java-Klassen problemlos in Ihrem JavaScript-Programmcode verwenden. Packen Sie dazu am besten zuerst die Klassen als Datei .jar. Anschließend kopieren Sie diese auf den Workplace Server in das Verzeichnis <WAS_Home>\WorkplaceServer\ lwp_lib. Um die Datei(en) über die Variable Classpath dem Server bekannt zu machen, öffnen Sie im Browser die Administratorkonsole des Workplace-Servers. Verwenden Sie dazu die Adresse http://<Server>:9091/admin.Nach der Anmeldung gelangen Sie über die Menüeinträge
Environment/Shared Libraries an die Stelle, an der Sie die benötigte Einstellung vornehmen können. Klicken Sie auf den Eintrag LotusWorkplaceLib. Im Fenster der Konfigurationseinstellungen ergänzen Sie unter Classpath alle auf den Server kopierten Dateien (Bild 1).

Starten Sie nach dem Speichern der Einstellungen und dem Abmelden von der Administratorkonsole den Workplace Server neu. Damit werden die neuen .jar-Dateien von der Java Virtual Machine (JVM) geladen.

Test der Java-Klassen

Beachten Sie, dass es sehr wichtig ist, die Java- Klassen genau zu testen, bevor Sie sie auf dem Workplace Server einrichten. Fehler sind nach der Integration schwer zu finden, können jedoch schwerwiegende Folgen haben. So kann es durchaus passieren, dass der Befehl System.exit(1) in der integrierten Java-Klasse an der falschen Stelle aufgerufen schon mal Teile des Workplace-Servers runterfährt. Nutzen Sie deshalb den Debugger bei der Entwicklung der Java- Klassen und erstellen Sie Testklassen zum Aufruf der eigentlichen Funktionen. Verwenden Sie Eclipse als DIE, dann steht Ihnen zum Test JUnit zur Verfügung.

Treten bei der späteren Verwendung der Java- Klasse im Workplace Designer dennoch Fehler auf, so werden fehlerhafte JavaScript-Aufrufe einer Java-Klasse oder -Methode zumindest in der Protokolldatei SystemOut.Log des Portalservers angezeigt. Direkte Fehler im Java-Programmcode (zum Beispiel durch fehlende Klassen in der .jar-Datei) führen jedoch zum Abbruch der Abarbeitung des die Klasse aufrufenden JavaScript- Programmcodes ohne Kommentar im Protokoll. Erstellen Sie deshalb zur Kontrolle Testausgaben. Im JavaScript-Programmcode der Komponente ist dies mit dem Befehl Println() und in den Java- Klassen mit System.out.println() möglich. In beiden Fällen werden die Ausgaben in die Protokolldatei des Portalservers geschrieben.

Beispiel

Im Beispiel gehen wir davon aus, dass uns eine Java-Klasse zur Umrechnung von Maßstabsangaben zur Verfügung steht. Diese besitzt eine öffentliche Methode umrechnen(), die drei Parameter benötigt: den Quell- und den Zielmaßstab sowie den umzurechnenden Wert. Die Maßstäbe werden dabei als numerische Werte von 1 bis 6 gekennzeichnet und als Integerwerte übergeben. Der umzurechnende Wert soll vom Typ double sein. Innerhalb der Klasse wird unter Verwendung einer Hilfsklasse der Startwert zuerst in die Originalgröße und anschließend in den Zielmaßstab umgerechnet. Als Ergebnis wird ein Wert vom Typ double zurückgegeben.

function createCalendarAppointment(locCalendarService:WorkplaceCalendar, _
startDate:Date, endDate:Date, subject:String, description:String, _
location:String ) {
// Eventuelle Exceptions müssen durch die rufende Routine abgefangen werden
var calEntry:com.ibm.workplace.api.calendar.data.CalendarEntry = _
locCalendarService.createCalendarEntry();
calEntry.setStartTime(startDate);
calEntry.setEndTime(endDate);
calEntry.setDescription(description);
calEntry.setSubject(subject);
calEntry.setLocation(location);
calEntry.setEventType(calEntry.TYPE_APPOINTMENT);
var entryIDText = locCalendarService.addCalendarEntry(calEntry);

Maske zur Anzeige des Ergebnisses

Im Workplace Designer entwickeln wir eine Maske zur Eingabe der Werte und zur Anzeige des Ergebnisses (Bild 2).

Das zu verwendende Schema Schema_Scale soll speziell für die Maske erstellt werden. Die Optionsschaltflächen zur Auswahl der Maßstäbe sind dabei in zwei Gruppen zusammengefasst. Damit kann jeder Gruppe ein Wert des Schemas zugeordnet werden. Detaillierte Angaben zur Maske, den Feldern und dem Schema enthält Tabelle 1.

Tabelle 1: Informationen zu Maske, Feldern und Schema

Feld	UIControl, Eigenschaften	Schemawert
Umzurechnender Wert	Edit Box	Wert
Ausgangsmaßstab	6 Radio Button; Radio group Name: radioGroupName; Start Value when selected: 1 bzw. 2, 3, 4, 5, 6; für ein Element Selected by Default: True	Start
Zielmaßstab	6 Radio Button; Radio group Name: radioGroupName2; End Value when selected: 1 bzw. 2, 3, 4, 5, 6; für ein Element Selected by Default: True	End
Wert im Zielmaßstab	Edit Box, Read-only: True	Ergebnis

Über die Schaltfläche Umrechnen! wird die Methode der Java-Klasse aufgerufen (Listing 2). Zuerst wird die Objektvariable converter als Instanz der Klasse ScaleConvert3() im Package com.fuchs.scale deklariert:

var converter = new com.fuchs.scale.ScaleConvert3();

Auslesen der Inhalte

Anschließend werden die Inhalte der einzelnen Felder aus dem aktuellen Dokument ausgelesen. Dabei wird gleichzeitig die Typkonvertierung entsprechend den Erfordernissen der Parameterdefinition der Java-Klasse vorgenommen. Zur Kontrolle werden die ermittelten Werte in die Protokolldatei des Portalservers geschrieben.

//Initialisieren der Java-Klasse
var converter = new com.fuchs.scale.ScaleConvert3();
//Wert aus Formular lesen
var start = parseInt(document.getStringValue("/Schema_Scale/start"));
// Schreiben des Wertes in die SystemOut.Log des Portalservers
println("start: "+start);
var end = parseInt(document.getStringValue("/Schema_Scale/end"));
println("end: "+end);
var wert = parseFloat(document.getStringValue("/Schema_Scale/wert"));
println("wert: "+wert);
//Aufruf der Methode in der Java-Klasse
var erg = converter.umrechnen(start, end, wert);
var ergtext = "" + erg + " cm";
println("ergebnis: "+ergtext);
//Ergebnis in das Formular schreiben
document.setStringValue("/Schema_Scale/ergebnis", ergtext);

Der Aufruf der Methode umrechnen() der Java- Klasse erfolgt nach den bekannten Konventionen der Punktnotation unter Angabe der Werte als Parameter:

var erg = converter.umrechnen(start, end, wert);

Das zurückgegebene Ergebnis wird zum einen wieder in die Protokolldatei und zum anderen in das Feld der Maske geschrieben (Bild 3).

Die Domino-API verwenden

Für den Aufruf der Domino-Klassen müssen diese der JVM bekannt sein. Analog zur Vorgehensweise bei der Verwendung eigener Java-Klassen müssen Sie deshalb die Datei ncso.jar auf den Workplace-Server in das Verzeichnis <WAS_Home>\ WorkplaceServerwp_lib kopieren und anschließend bekannt machen. Laufen der Workplaceund der Domino-Server auf dem gleichen Computer, entfällt der zweite Schritt. Sie finden die Datei ncso.jar auf dem Domino-Server bei einer Standardinstallation im Verzeichnis <Domino_ Home>\Domino\Data\Domino\Java. Diese Datei enthält die Domino-Klassen und die Object Request Broker (ORB), die einen Remote- Aufruf des Domino-Servers ermöglichen. Voraussetzung auf Seiten des Domino-Servers ist, dass sowohl der HTTP- als auch der DIIOP-Task gestartet wurde. Die Vorgehensweise entspricht damit der beim Zugriff über CORBA (Common Object Request Broker Architecture) auf den Domino- Server.

Zum Test der Funktion verändern wir die Maske Buch unseres bisher entwickelten Beispiels. Sie wird um je ein UIControl Label und EditBox erweitert. Diese sind nur sichtbar, wenn ein Buch den Status Ausgeliehen besitzt. Ist dies der Fall, kann in das Feld ein Name eingetragen werden, welcher im Schemawert Vorbestellen gespeichert wird. Fügen Sie dem Schema Schema_Buch einen entsprechenden Wert hinzu. Wird das Buch zurückgegeben, soll an den Interessenten automatisch eine E-Mail verschickt werden, dass das Buch wieder verfügbar ist. Dazu wollen wir die Domino-API verwenden. Zu dem Zweck modifizieren wir den Programmcode der Schaltfläche Abgeben (Bild 4). Es soll direkt in der Datei mail. box auf dem Domino-Server ein Dokument erstellt werden. Besitzt dieses die nötigen Felder, wird es an den Empfänger ausgeliefert. Für den Zugriff auf den Domino-Server kann ein spezieller Benutzer, zum Beispiel wseadmin, auf dem Domino-Server eingerichtet werden.

Create Session

Die benötigte Session wird über die Methode createSession() der Klasse NotesFactory erstellt. Beim Aufruf werden der Name des Servers, der Name des Benutzers und dessen Passwort übergeben. Damit entfällt die Aufforderung des Passworts während der Abarbeitung des Programmcodes

var notesfactory = lotus.domino.NotesFactory;
se = notesfactory.createSession("<Server>","<Username>","<
Password>");

Das Weitere entspricht der üblichen Vorgehensweise – Zugriff auf die Datenbank, Erstellung und Speichern des Dokuments. Listing 3 zeigt den kompletten Programmcode.

document.setStringValue("/Schema_Buch/Status", "Vorhanden");
//Einbinden der Domino Klassen
var notespack = lotus.domino;
//Inhalt des Feldes Vorbestellen (enthält Namen des Interessenten) auslesen
var user = document.getStringValue("/Schema_Buch/Vorbestellen")
if (user!="") {
var notesfactory = notespack.NotesFactory;
try {
se = notesfactory.createSession("<Server>","<username>","password");
//Zugriff auf die mail.box
db = se.getDatabase("","mail.box");
//Dokument erstellen
doc = db.createDocument();
//Feldwerte setzen
doc.replaceItemValue("Form","Memo");
doc.replaceItemValue("Recipients", user);
doc.replaceItemValue("From","WSEMail");
doc.replaceItemValue("Subject","Ihr bestelltes Buch ist verfügbar");
doc.replaceItemValue("Body", _
"Das von Ihnen bestellte Buch wurde abgegeben und ist wieder verfügbar.");
//Mit dem Speichern wird das Dokument automatisch zugestellt.
doc.save(true, true);
//Objektzuweisungen aufheben
doc.recycle();
db.recycle();
se.recycle();
} catch (e) {
e.printStackTrace();
}
}

Alternativ können Sie natürlich auch wieder eine externe Java-Klasse programmieren, welche den eigentlichen Domino-Aufruf realisiert, und diese, wie bereits weiter oben gezeigt, in Ihrer Workplace Komponente verwenden. Diese Variante bietet den Vorteil, dass Änderungen beim Aufruf des Domino Servers möglich sind, ohne dass dies Einfluss auf den Programmcode innerhalb der Komponente hat. Sie müssen lediglich sicherstellen, dass die benutzten Schnittstellen sauber definiert sind und bei Modifikationen an der externen Klasse unverändert bestehen bleiben.