NotesDXLExporter und NotesDXLImporter

15.07.2006 von Martin Kuppinger

Die beiden Klassen NotesDXLExporter und NotesDXLImporter werden für das Lesen und Schreiben von DXL-Dateien benötigt, also XML-Dokumenten im Format der spezifischen Domino DTD, die für den Austausch mit Lotus Domino genutzt wird. Sie sind für den Austausch von XML-Dokumenten von zentraler Bedeutung.

Im Artikel „Gestaltungselemente importieren“, der Ausgabe 5/2006, der sich schon einmal mit dem DXLImporter befasste, lag der Schwerpunkt auf dem konkreten Import von Gestaltungselementen und der Nutzung auch über eine externeVisual Basic-Anwendung. In diesem Artikel werden die Klassen und ihre Eigenschaften und Methoden ganz allgemein betrachtet, mit Fokus auf der grundsätzlichen Vorgehensweise und auf Neuerungen vor allem des Release 7. Darüber hinaus werden wir den Aufbau von DTDs näher betrachten, denn die beiden DXL-Klassen lassen sich sinnvoll nur nutzen, wenn man mit der Struktur der Domino DTD gut vertraut ist – und dazu muss man DTDs „lesen“ können.

NotesDXL Exporter

Die Klasse NotesDXLExporter ist für die Umsetzung von Daten aus einer Domino-Datenbank in ein XML-Dokument zuständig, das auf der Domino DTD basiert. Damit können Informationen zwischen Domino-Systemen ausgetauschtwerden. Die erzeugten XML-Dokumente können aber von externen Tools auch konvertiert werden, wenn ein anderes Format benötigt wird. Allerdings stellt sich in diesem Fall die Frage, ob man nicht bereits in Domino die entsprechend angepassten Dokumente erzeugen möchte. Das lässt sich mit dem Ansatz desPipelinings allerdings auch in Verbindung mit NotesDXLExporter realisieren, indem eben nicht in einen Stream, sondern an eines der transformierenden Objekte übergeben wird.

Beim Export wird in den meisten Fällen ein Datenstrom erzeugt, der in einer Datei gespeichert wird. Alternativ dazu kann die Ausgabe aber auch in andere Objekte erfolgen. Besonders wichtig sind die verschiedenen Parser, mit denen eine weitere Verarbeitung der Informationen erfolgt. Das wird deutlich, wenn man die Struktur der Methode CreateDXLExporter in der Klasse NotesSession betrachtet. Hier lassen sich optionale Parameter für die Ein- und Ausgabeobjektesetzen. Eine Alternative dazu ist die Verwendung der Methoden SetInput und SetOutput von Notes DXLExporter.'

Bei den Eingabeobjekten können Notes-Datenbanken, Dokumente, Dokumentsammlungen (Document Collections) oder Note Collections eingesetzt werden.

Ausgabe

Bei der Ausgabe hat man dagegen die Option, ein Stream-Objekt, ein Rich-Text-Objekt oder das Pipelining an ein Objekt zu verwenden, das XMLDaten verarbeiten kann. Folgende Optionen stehenzur Verfügung:

NotesDOMParser
NotesDXLImporte
NotesSAXParser
NotesXSLTransformer

Es gibt also die drei verschiedenen Varianten von Parsern respektive Transformatoren bei Domino, mit denen XML-Dokumente verarbeitet werden können, sowie den NotesDXLImporter als Gegenstück zum Exporter. In allen vier Fällen wird mit dem Pipelining ohne Zwischenspeicherung gearbeitet. Die Ausgabe des NotesDXLExporters wird vielmehr unmittelbar als Eingabe für das Zielobjekt verwendet. Das ist ein effizienter Mechanismus, der zudem bei der Entwicklung relativ einfach ist, weil man sich eben die Zwischenspeicherung und damit beispielsweise das Schreiben und Lesen von Streams erspart.

Die Parser und Transformer werden eingesetzt, wenn der Output gleich weiter verarbeitet werden soll, vor allem um nur einen Teil der Informationen in der vom DXLExporter erzeugtenAusgabe im XML-Dokument zu belassen.

Der NotesDXLExporter hat neben den Klassen SetInput und SetOutput zwei weitere Klassen zu bieten. Mit Process, der bereits seit dem Release 6 verfügbaren Methode, kann die Verarbeitung erfolgen, wobei auch das Pipelining unterstützt wird. Export dagegen unterstützt nur den direkten Export, wobei eine Zeichenkette generiert wird. Die Zeichenkette kann anschließend beispielsweise in eine Datei geschrieben werden. Die Verwendung von Export ist etwas einfacher, bietet allerdings nicht annähernd so viele Möglichkeiten wie Process in Verbindung mit Streams oder dem Pipelining.

Eigenschaften

Bei den Eigenschaften sind insbesondere SchemaLocation und ValidationStyle erwähnenswert, die mit dem Release 7 neu eingeführt wurden. Mit SchemaLocation kann angegeben werden, wo sich die Datei mit der Beschreibung des Schemas für die DXL befindet, die beim Export erstellt wird. Standardmäßig wird auf die Datei domino_7_0.xsd im Unterverzeichnis xmlschemas des Programmverzeichnisses von Lotus Domino verwiesen. Bei der Datei handelt es sich um eine XML-Schema-Datei und nicht um eine DTD. Hintergrund ist, dass ab Domino 7 alternativ zu den DTDs für DXL auch XLMSchemadateien (XSD) unterstützt werden. Derzeitwerden für jedes Zwischenrelease die DTDs und XSDs parallel ausgeliefert.

In direktem Zusammenhang zu dieser Eigenschaftmsteht der ValidationStyle mit den drei folgenden Optionen:

VALIDATIONSTYLE_NONE(O) gibt an, dass keine Validierung erfolgt. Das ist die Ausnahme.
VALIDATIONSTYLE_DTD (1) ist Standard und legt die DTD für die Validierung fest.
VALIDATIONSTYLE_SCHEMA (2) ist eine neue Option, mit der die Verwendung des Schemas definiert wird. Nur in diesem Fall ist auch die Option SchemaLocation erforderlich – und auch das nur, wenn das Schema an einer anderen Stelle im System abgelegt ist.

NotesDXLImporter

Das Gegenstück zu NotesDXLExporter ist Notes DXLImporter. Damit können XML-Dokumente direkt in Lotus Domino-Datenbanken eingelesen werden. Diese Klasse ist etwas komplexer, da beim Export auf einer bekannten, fehlerfreien Datenstruktur – den Domino-Datenbanken – gearbeitet wird, während es beim Import durchaus zu Problemen kommen kann, wenn die Daten doch nicht in der richtigen Struktur vorliegen. Der Import ist von allen Objekten möglich, in die auch exportiert werden kann. Hier ist Lotus Domino relativ flexibel. Die Daten können aus Rich- Text- und Stream-Objekten, direkt vom DXLExporter oder, ebenfalls über das Pipelining, von den drei XML-Parsern und -Transformern übernommen werden.

Als zusätzliche Methoden zu SetInput, SetOutput, Process und Import gibt es noch GetFirstImportedNoteID und GetNetxtImportedNoteID zur Navigation durch die eingelesene Liste von Notes.

Bei den Eigenschaften steuern verschiedene Optionen, ob ACLs, Dokumente und das Design importiert werden oder nicht – abhängig davon, was erreicht werden soll. Interessant ist aber ein anderer Punkt: Die Eigenschaft InputValidation- Option erlaubt nur die Festlegung, ob mit einer DTD für die Validierung des XML-Dokuments mit den zu importierenden Daten gearbeitet werden soll oder nicht. Der Zugriff auf XMLSchemas wird auch in der Version 7 von Lotus Domino noch nicht angeboten.

Beispiel für einen Agent

Listing 1 zeigt ein Beispiel für einen Agent, mit dem ein Gestaltungselement aus einem XMLDokument eingelesen wird. Die Datei wird als Stream geöffnet. Die Eigenschaft für den Import von Designelementen wird gesetzt, bevor die Verarbeitung erfolgt. Der eigentliche Import ist dabei in wenigen Codezeilen erledigt.

Sub Initialize Dim ws As New NotesUIWorkspace Dim se As New NotesSession Dim db As NotesDatabase Dim stream As NotesStream Dim im As NotesDXLImporter Dim datName As Variant Set db = se.CurrentDatabase 'Datenstrom erzeugen Set stream = se.CreateStream() datName = ws.OpenFileDialog(False, _ "Zu importierendes Gestaltungselement wählen",,"c:\temp") If (Isempty(datName)) Then Exit Sub End If 'Quelldatei für Datenstrom festlegen Call stream.Open(datName(0)) 'DXLImporterobjekt unter Angabe der Quelle und des Ziels erzeugen Set im = se.CreateDXLImporter(stream, db) 'Import von Designdokumenten aktivieren im.DesignImportOption = 2 'Importprozess ausführen Call im.Process() Call stream.Close() End Sub

Beim Import liegt die Herausforderung vor allem darin, mit korrekten Daten zu arbeiten. Am einfachsten ist das, wenn diese auch von Lotus Domino erzeugt wurden. Andernfalls muss man sich intensiv mit der DTD bzw. dem Schema auseinander setzen, um gültige XML-Dokumente für den Import in Lotus Domino zu erzeugen.