In Lotus Notes Domino wird in der Version 7 die Erstellung von Web Services innerhalb von Datenbanken mit dem gleichnamigen Gestaltungselement direkt unterstützt. Die Programmierung kann in LotusScript oder Java erfolgen. Die Erstellung der WSDL-Datei (Web Service Description Language) übernimmt der Domino Designer. Damit besteht die Möglichkeit, im Rahmen von verteilten Anwendungen in Domino Datenbanken gespeicherte Daten direkt zu nutzen.
In den beiden letzten Ausgaben der Expert's Inside Lotus Notes/Domino haben wir uns mit dem Aufbau der WSDL-Datei sowie der Möglichkeit eines Test-Clients mittels SOAP beschäftigt. Daneben stand natürlich die Vorgehensweise zur Erstellung eines LotusScript Web Service, welcher ein oder mehrere Ergebnisse zurückliefert, im Mittelpunkt. Dabei sind wir davon ausgegangen, dass bei der Ausführung des Web Service keine Fehler auftreten. Auf eine Fehlerbehandlung wurde deshalb verzichtet. Da diese Vorgehensweise kaum den Anforderungen in der Praxis gerecht wird, beschäftigt sich der folgende Artikel mit der Thematik Fehlerbehandlung.
Fehler ohne Fehlerbehandlung
Die Anfrage eines Clients an einen Web Service erfolgt über SOAP (Simple Access Object Protocol). Dieser SOAP-Request wird vom Web Service mit einer SOAP-Response beantwortet. Tritt nun bei der Abarbeitung eines Web Service ein Fehler auf, wird dieser in der Response-Datei an den Client übermittelt. Bild 1 zeigt die SOAP-Response mit Hilfe des Tools SOAPUI 1.5 (www.soapui.org). Der verwendete Web Service entsprach dem im vorigen Artikel vorgestellten zur Abfrage aller Reiseziele für eine bestimmte Reisenummer. Im Programmcode wurde dabei auf jegliche Überprüfung, ob es eine Reise mit der angeforderten Nummer gibt, und auf etwaige weitere Fehlerbehandlungen verzichtet.
Erfolgt zumindest eine Überprüfung mittels einer If-Anweisung auf das Vorhandensein einer Reise mit der übergebenen Nummer, wird kein Fehler erzeugt, sondern das ermittelte Ergebnis, in diesem Fall die Mitteilung bezüglich der falschen Nummer, zurückgegeben (Bild 2). Der Client erhält in diesem Fall keinen Anhaltspunkt, dass ein Fehler aufgetreten ist. Lediglich die Analyse des Ergebnisses könnte einen Hinweis darauf liefern. Um im Client auf einen Fehler reagieren zu können, ist somit dessen Übermittlung und eindeutige Kennzeichnung in der SOAP-Response erforderlich.
Festlegungen der SOAP-Spezifikation
Die für die Fehlermeldung zu verwendende Form ist in der SOAP-Spezifikation 1.1 (www.w3.org/TR/2000/NOTE-SOAP-20000508) im Abschnitt 4.4 SOAP Fault festgelegt. Dort wird das Element Fault definiert. Dieses Element übermittelt den Fehler innerhalb einer SOAP-Mitteilung. Wenn das Element Fault in einer SOAP-Nachricht enthalten ist, befindet es sich einmal innerhalb des Elements Body. Das Element Fault selbst kann vier Unterelemente enthalten: faultcode, faultstring, faultactor sowie detail. Dabei sind die Unterelemente faultcode und faultstring erforderlich, faultactor und detail sind optional. Tabelle 1 enthält eine Übersicht der Unterelemente des Elements Fault.
|
Element |
Optional |
Beschreibung |
|
Faultcode |
Nein |
Für die Auswertung des Fehlers mittels Software muss das Element faultcode eine eindeutige Fehlerbeschreibung enthalten. Der Aufbau der Fehlerbeschreibung muss einem XML-Namespace entsprechen. |
|
Faulstring |
Nein |
Das Element faultstring soll eine Beschreibung des aufgetretenen Fehlers im Klartext enthalten. Es ist für die Auswertung durch den Menschen bestimmt. |
|
Faultactor |
Ja |
Das Element faultactor kann in Form eines URI die Quelle des Fehlers angeben. |
|
Detail |
Ja |
Über das Element detail können anwendungsspezifische Fehlerinformationen übermittelt werden. |
Die optionalen Elemente faultactor und detail können bei der Implementierung eines Web Service innerhalb einer Notes-Datenbank mittels LotusScript nicht verwendet werden. Dies ist nur bei der Programmierung mit Java möglich.
Umsetzung der SOAP-Spezifikation mit LotusScript
Für die Verwendung des Elements Fault gibt es die LotusScript-Klasse WS_Fault. Sie ist in der Datei LSXSD.LSS definiert (Listing 1). In der Hilfe des Domino Designer findet sich kein Hinweis sowie eine Fehlernachricht bestimmt werden. Über die entsprechenden get-Methoden ist die Abfrage der Werte möglich.
PUBLIC CLASS WS_FAULT
PRIVATE Fault As BOOLEAN
PRIVATE FaultString As STRING
SUB setFault (value As BOOLEAN)
Fault = value
END SUB
FUNCTION getFault () As BOOLEAN
getFault = Fault
END FUNCTION
SUB setFaultString (value As STRING)
FaultString = value
END SUB
FUNCTION getFaultString () As STRING
getFaultString = FaultString
END FUNCTION
END CLASS
Für die Fehlerbehandlung in einem LotusScript Web Service sind fünf Schritte notwendig:
-
Einbinden der Datei LSXSD.LSS
-
Übergabe eines Parameters
-
Aktivierung der allgemeinen Fehlerbehandlung in LotusScript
-
Erzeugung des Fehlers
-
Definition der Fehlermeldung
Nach dem Öffnen des Gestaltungselements binden Sie zuerst die Datei LSXSD.LSS unter Options mit dem Befehl
%Include "lsxsd.lss"
ein.
Aufruf eines zusätzlichen Parameters
Als Nächstes verwenden Sie beim Aufruf der Funktion oder der Subroutine, welche den Fehler erzeugen soll bzw. kann, einen zusätzlichen Parameter vom Typ WS_Fault. Diesen müssen Sie als letzten innerhalb der Parameterliste angeben. Andernfalls erhalten Sie beim Kompilieren des Programmcodes eine Fehlermeldung (Bild 3).
Function getReiseziele(Reisenummer As String, f1 As
WS_Fault) As FeldReiseziele
Um auch unerwartete Fehler abzufangen, aktivieren Sie die Fehlerbehandlung:
On Error Goto Fehler
Innerhalb der Routine erzeugen Sie mit der Methode setFault() an den notwendigen Stellen einen Fehler:
f1.setFault(True)
Anschließend definieren Sie den zu übergebenden Fehlertext:
Call f1.setFaultString("Keine Reise mit der angegebenen
Nummer vorhanden.")
Listing 2 zeigt den um die Verwendung des Elements Fault erweiterten Beispiel-Web Service. Tritt beim Aufruf des Web Service ein Fehler auf, wird der faultcode vom Domino Server generiert und zusammen mit dem faultstring in der SOAPResponse übergeben. Im Beispiel wird eine ungültige Reisenummer beim Aufruf des Web Service verwendet. Bild 4 zeigt die daraus resultierende SOAP-Response. Im Unterschied zur Vermeidung des Fehlers mittels einer If-Anweisung, bei der als normaler Rückgabewert ebenfalls ein Fehlertext zurückgeliefert werden kann (Bild 2), ist das jetzige Ergebnis über das Element Fault eindeutig als Fehlermeldung zu erkennen.
Class ReisezielInfo
Sub new
Set se = New NotesSession
Set db = se.CurrentDatabase
Set vw = db.GetView("AlleReisen")
End Sub
Function getReiseziele(Reisenummer As String, f1 As WS_Fault) As
FeldReiseziele
On Error Goto Fehler
Dim doc As NotesDocument
Dim i As Integer
Set getReiseziele = New FeldReiseziele
Set doc = vw.GetDocumentByKey(Reisenummer)
If doc Is Nothing Then
f1.setFault(True)
Call f1.setFaultString("Keine Reise mit der angegebenen Nummer
vorhanden.")
Else
Redim getReiseziele.Reiseziele(0 To Ubound(doc.Reiseziel))
For i = 0 To Ubound(doc.Reiseziel)
getReiseziele.Reiseziele(i) = doc.Reiseziel(i)
Next
End If
Exit Function
Fehler:
f1.setFault(True)
Call f1.setFaultString("Ein Fehler ist aufgetreten.")
Exit Function
End Function End Class
Die im Artikel beschriebene Beispieldatenbank steht auf der Website des Autors zum kostenlosen Download zur Verfügung.