Ausarbeitung_DA_FINAL - NeoOffice Writer

Transcription

Ausarbeitung_DA_FINAL - NeoOffice Writer
DIPLOMARBEIT – Database Technology Research Group, Prof. Dr. Klaus R. Dittrich / Prof. Abraham Bernstein
Department of Informatics
DBDoc
Entwurf und Implementierung
einer Anwendung zur partiellen
Automation des DokumentationsProzesses für Datenbanken
Diplomarbeit im Fach Informatik
Sascha Nedkoff
Zürich, Switzerland
Matrikelnummer: 00-709-733
Betreuer:
Professor:
Boris Glavic
Prof. Dr. Klaus R. Dittrich
Prof. Abraham Bernstein
Abgabe:
20. Januar 2008
University of Zurich
Department of Informatics (IFI)
Binzmühlestrasse 14, CH-8050 Zürich, Switzerland
iii
Abstract
Nowadays most relational database systems support the specification and storage of user-defined comments for database objects. Those comments can be considered as a rudimentary
documentation of the database schema. But alone they are insufficient and inconvenient to
document a database, because they can only be accessed in a cumbersome way and for a
documentation many other schema informations are also relevant.
Within this thesis an application for a partial automation of the documentation process is developed and implemented, which is capable to generate a database documentation by accessing the user-defined comments and schema informations. Thereby it should generally
support various output formats and various database systems as well as database design patterns.
iv
v
Zusammenfassung
Heutzutage unterstützen die meisten relationalen Datenbanksysteme die Spezifikation und
Speicherung von benutzerdefinierten Kommentaren für Datenbankobjekte. Diese Kommentare können als rudimentäre Dokumentation eines Datenbankschemas angesehen werden.
Allein sind sie aber ungenügend und nicht komfortabel, um Datenbanken zu dokumentieren.
Einerseits weil nur umständlich auf sie zugegriffen werden kann und andererseits weil für
eine Dokumentation viele andere Schemainformationen ebenfalls relevant sind.
Im Rahmen dieser Diplomarbeit wird eine Anwendung zur partiellen Automation des Dokumentations-Prozesses erstellt, welche über Zugriffe auf Schemainformationen und benutzerdefinierte Kommentare eine Dokumentation dieser Datenbank generieren kann. Dabei sollen generell verschiedene Ausgabeformat und verschiedene Datenbankanbindungen möglich
sein sowie Datenbankentwurfsmuster unterstützt werden können.
vi
vii
Inhaltsverzeichnis
1 Einleitung............................................................................................................................1
1.1 Motivation....................................................................................................................1
1.2 Ziele der Arbeit.............................................................................................................2
1.3 Aufbau der Arbeit.........................................................................................................3
2 Grundlagen.........................................................................................................................4
2.1 Software Dokumentation..............................................................................................4
2.1.1 Aufgaben der Dokumentation...............................................................................4
2.1.2 Arten von Dokumentationen.................................................................................5
2.1.2.1 Projektdokumentation...................................................................................5
2.1.2.2 Produktdokumentation..................................................................................6
2.1.3 Problematik von Dokumentationen......................................................................7
2.2 Automatische Software Dokumentation.......................................................................7
2.3 Dokumentation von Programmcode.............................................................................8
2.4 Dokumentation von Datenbanken................................................................................8
3 Verwandte Arbeiten.........................................................................................................10
3.1 Werkzeuge für die Dokumentation von Programmcode............................................10
3.1.1 Javadoc................................................................................................................10
3.1.1.1 Tags.............................................................................................................11
3.1.1.2 Doclet..........................................................................................................12
3.2 Werkzeuge für die Dokumentation von Datenbanken................................................13
3.2.1 DBScribe.............................................................................................................13
3.2.2 SQL Doc.............................................................................................................14
3.2.3 SqlSpec...............................................................................................................15
3.2.4 ApexSQL Doc.....................................................................................................15
3.2.5 Zusammenfassende Feststellungen über die Werkzeuge....................................16
4 Anforderungsspezifikation..............................................................................................18
4.1 Grundlegende Anforderungen....................................................................................18
4.1.1 Anbindung unterschiedlicher Datenbanksysteme...............................................18
4.1.2 Verschiedene Ausgabeformen und Formate.......................................................18
4.1.3 Unterstützung von Datenbankentwurfsmuster....................................................19
4.1.4 Kommentare und Annotationen..........................................................................19
4.1.5 Flexible Architektur............................................................................................20
4.1.6 Generisches Datenmodell...................................................................................20
4.1.7 Weitere Anforderungen.......................................................................................21
4.2 Spezielle Anforderungen............................................................................................21
viii
5 Design................................................................................................................................22
5.1 Datenmodell...............................................................................................................22
5.1.1 Schnittstellenhierarchie.......................................................................................23
5.1.2 Erzeugung der Objekte.......................................................................................26
5.1.3 Namen und Referenzierung................................................................................26
5.1.4 Verlinkung...........................................................................................................27
5.2 Plug-in Architektur.....................................................................................................29
5.2.1 Model-Plug-in.....................................................................................................32
5.2.2 Input-Plug-in.......................................................................................................32
5.2.3 Output-Plug-in....................................................................................................32
5.2.4 Transformator-Plug-in........................................................................................33
5.2.5 Plug-in Manager.................................................................................................33
5.3 Kommentare und Annotationen.................................................................................34
5.3.1 Speicherung........................................................................................................34
5.3.2 Annotationen.......................................................................................................35
5.3.2.1 Tags mit Informationen...............................................................................35
5.3.2.2 Tags zur Formatierung................................................................................39
6 Implementierung..............................................................................................................41
6.1 Datenmodell...............................................................................................................41
6.2 Kommentare und Tags................................................................................................41
6.2.1 Tag-Definitionen.................................................................................................42
6.2.2 Parser..................................................................................................................44
6.3 Applikationsmanager..................................................................................................45
6.3.1 XML-Konfigurationsdatei..................................................................................45
6.3.2 Kommandozeilen Argumente.............................................................................47
6.3.3 Protokollierung...................................................................................................47
6.4 Plug-ins.......................................................................................................................47
6.4.1 Standard-Model-Plug-in.....................................................................................48
6.4.2 PostgreSQL-Input-Plug-in..................................................................................49
6.4.3 Output-Plug-ins...................................................................................................51
6.4.3.1 HTML-Output-Plug-in................................................................................51
6.4.3.2 Konsolen-Output-Plug-in............................................................................56
6.4.4 Transformator-Plug-ins.......................................................................................56
6.4.4.1 Kommentar-Transformator.........................................................................56
6.4.4.2 SQL-Reconstructor.....................................................................................60
6.4.4.3 View-Properties-Setter................................................................................61
6.4.4.4 Simulated Constraint Analyser...................................................................62
7 Tests...................................................................................................................................64
ix
7.1 Performance................................................................................................................64
7.2 JUnit...........................................................................................................................66
8 Weiterführende Arbeiten.................................................................................................67
8.1 Graphische Benutzeroberfläche (GUI).......................................................................67
8.2 Weitere Datenbankanbindungen.................................................................................68
8.3 Weitere Ausgabeformate............................................................................................68
8.4 Erweiterung des Datenmodells...................................................................................68
8.5 Weitere Transformatoren............................................................................................69
8.6 Persistente Speicherung der Informationen über Datenbankobjekte..........................69
9 Zusammenfassung und Schlussfolgerungen..................................................................70
x
xi
1 Einleitung
1 Einleitung
1.1 Motivation
In der Softwareentwicklung sollte dem Dokumentationsprozess sowie der Dokumentation
eine wichtige Rolle zukommen. Dokumentationen erfüllen verschiedene wichtige Aufgaben, vom Hilfsmittel für eine bessere Kommunikation bis hin zur Wissenssicherung. Ebenso
wie Programme und Programmcode einer Dokumentation bedürfen so benötigen auch Datenbanken beziehungsweise Datenbankschemas eine ausführliche Dokumentation. Insbesondere wenn Datenbanken grösser und komplexer werden, aber auch wenn sie über längere
Zeit im Einsatz sein sollen, sind gute Dokumentationen unerlässlich.
Heutzutage bieten viele Datenbanksysteme die Möglichkeit benutzerdefinierte Kommentare
für einzelne Datenbankobjekte zu spezifizieren und zu speichern. Diese Möglichkeit kann
eingesetzt werden um Datenbankschemas rudimentär zu dokumentieren. Jedoch ist eine solche Möglichkeit allein ungenügend und nicht komfortabel um ein Datenbankschema ausreichend zu dokumentieren. Denn auf die Kommentare kann nur umständlich zugegriffen werden und es ist keine Navigation zwischen Kommentaren von verschiedenen Datenbankobjekten möglich. Ausserdem möchte man eine separate Dokumentation ohne direkt auf die
Datenbank und deren Objekte zugreifen zu müssen und eine vollständige Dokumentation
sollte neben Kommentaren für Datenbankobjekte auch eine Vielzahl weiterer Informationen, welche das Datenbankschema detaillierter beschreiben, enthalten.
Wie bei der Dokumentation von Programmcode bietet sich auch bei der Dokumentation von
Datenbankschemas der Einsatz von Werkzeugen an, um automatisch die benutzerdefinierten
Kommentare sowie weitere relevante Informationen aus dem Programmcode beziehungsweise dem Datenbankschema auszulesen oder abzuleiten und daraus eine Dokumentation zu
generieren.
Für die automatische Generierung von Dokumentationen für Datenbanken existieren bereits
verschiedene Werkzeuge. Jedoch weisen die momentan vorhandene Werkzeuge viele Einschränkungen auf. Zum einen können die meisten Werkzeuge nur Datenbanken auf bestimmten Datenbanksystemen dokumentieren und zum anderen werden nur wenige Ausgabeformate angeboten und es existiert keine Möglichkeit neue Ausgabeformate oder Datenbankanbindungen hinzuzufügen. Ebenfalls bieten sie wenig Freiheiten auf den Inhalt der
Dokumentation Einfluss zu nehmen und bieten keine Unterstützung bei der Dokumentation
von Datenbankentwurfsmustern.
1
1.2 Ziele der Arbeit
1.2 Ziele der Arbeit
Im Rahmen dieser Diplomarbeit soll, angelehnt an Javadoc, eine Anwendung zur partiellen
Automation des Dokumentations-Prozesses für Datenbanken entwickelt werden. Die Anwendung soll über Zugriffe auf Datenbankschema-Informationen und benutzerdefinierte
Kommentare eine Dokumention einer Datenbank generieren können. Ziel ist es ein voll
funktionstüchtige und getestete Anwendung zu entwerfen und zu implementieren sowie Lösungsvorschläge für die grundlegenden Probleme zu erarbeiten und die Machbarkeit und
Eignung anhand der Implementierung aufzuzeigen.
Die grundlegenden Herausforderungen beim Entwurf der Anwendung sind erstens, die
Schaffung einer Möglichkeit für die Anwendung um unterschiedliche relationale Datenbanksysteme unterstützen zu können. Damit beliebige relationale Datenbanken auf unterschiedlichen Datenbanksystemen dokumentiert werden können. Zweitens, dass die Anwendung grundsätzlich in der Lage sein muss beliebige Ausgabeformate für die Dokumentation
zu unterstützen. Neben den von der Anwendung angebotenen Ausgabeformaten soll es
ebenfalls möglich sein beliebige neue Ausgabeformat hinzuzufügen. Deshalb ist es von zentraler Bedeutung eine flexible Architektur sowie klare Schnittstellen zu entwerfen, um diese
Anforderung erfüllen zu können. Zusätzlich soll die Anwendung einen Mechanismus anbieten um die Dokumentation von Datenbankentwurfsmustern zu unterstützen. Dadurch soll es
möglich werden Datenbankentwurfsmuster in der Dokumentation angemessen zu dokumentieren. Als Beispiel für eine grössere und komplexere Datenbank, welche mehrere Entwurfsmuster verwendet, wird in dieser Arbeit die sesamDB1 verwendet. Anhand dieser Datenbank
sollen die Möglichkeiten zur Unterstützung von Datenbankentwurfsmustern getestet werden.
Weitere wichtige Anforderungen an die Anwendung sind, dass neben der grundsätzlichen
Unterstützung von verschiedenen Datenbankanbindungen, mindestens eine konkrete Anbindung für PostgreSQL Datenbanksysteme entwickelt wird. Ebenfalls soll neben der grundsätzlichen Möglichkeit verschiedene Ausgabeformate zu erzeugen, mindestens eine konkrete Lösung zur Generierung von HTML-Dokumentationen implementiert werden.
Angelehnt an Javadoc soll zusätzlich eine Möglichkeit angeboten werden um Annotationen
in benutzerdefinierten Kommentaren zu unterstützen. Mit solchen Annotationen soll es
möglich sein spezielle Informationen in Kommentaren auszuzeichnen, Kommentare zu formatieren sowie Referenzen auf andere Datenbankobjekte zu setzen.
1 http://www.sesamswiss.ch
2
1 Einleitung
1.3 Aufbau der Arbeit
Die vorliegende Diplomarbeit ist thematisch in neun Kapiteln gegliedert:
Im Kapitel 2 werden zuerst die Grundlagen bezüglich Softwaredokumentationen im allgemeinen und automatischer Generierung von Softwaredokumentationen im speziellen beschrieben.
Kapitel 3 befasst sich im ersten Teil mit Javadoc als Werkzeug für die Dokumentation von
Programmcode und in einem zweiten Teil mit den schon vorhandenen Werkzeugen zur Dokumentation von Datenbanken.
Im Kapitel 4 werden die allgemeinen Anforderungen an eine Anwendung zur Dokumentation von Datenbanken und die im Rahmen dieser Arbeit geltenden speziellen Anforderung
spezifiziert.
Kapitel 5 beschreibt den Entwurf der Anwendung und erläutert die Konzepte, welche entwickelt wurden, um den gestellten Anforderungen gerecht zu werden.
Im Kapitel 6 wird detaillierter auf die Implementierung der Anwendung eingegangen und
wichtige Ausschnitte beleuchtet.
Kapitel 7 enthält Information über die durchgeführten Performance- und JUnit-Tests.
Im Kapitel 8 werden weiterführende Arbeiten und Erweiterungen der entwickelten Anwendung besprochen.
Kapitel 9 schliesst die Arbeit mit einer Zusammenfassung und Schlussfolgerungen ab.
3
2 Grundlagen
2 Grundlagen
2.1 Software Dokumentation
Dokumentationen spielen in allen Bereichen der Informatik eine wichtige Rolle. Nicht nur
bei Datenbanken sondern auch in der Softwareentwicklung sind Dokumentationen von grosser Bedeutung.
Bei der Entwicklung von Software entsteht kein materielles Produkt. Alle Entwicklungstätigkeiten manifestieren sich letztlich nur in Form von Dokumenten (im weitesten Sinn ist
auch Programmcode ein Dokument). Den Dokumenten kommt daher in der Softwareentwicklung eine besondere Bedeutung zu [Glinz01].
Genau wie bei der Entwicklung von Software entsteht auch bei der Entwicklung von Datenbanken kein materielles Produkt und die Entwicklungstätigkeiten manifestieren sich nur in
Form von Datenbankschemas. Diese können im weitesten Sinn ebenfalls als Dokument angesehen werden und genau wie bei den Dokumenten in der Softwareentwicklung kommt ihnen ein hoher Stellenwert zu.
2.1.1 Aufgaben der Dokumentation
Wie in [Glinz01] beschrieben, erfüllen Dokumentation drei Hauptaufgaben:
●
Wissenssicherung: Die Informationen aus den Köpfen holen
Das Wissen (Know-How) über ein System macht einen beträchtlichen Teil des Werts
eines Systems aus. Die Dokumentation hat die Aufgabe, dieses Wissen schriftlich
oder elektronisch festzuhalten, damit es gesichert ist und nicht verloren geht.
●
Kommunikation: Reden miteinander genügt nicht
Eine geordnete Systementwicklung und -pflege ist ohne Kommunikation nicht möglich. Dies gilt sogar für Ein-Personen-Projekte, wenn das Produkt länger als ein paar
Wochen leben soll. Mündliche Kommunikation ist bei Arbeiten in einem kleinen
Personenkreis sehr effizient. Ausschliesslich mündliche Kommunikation verursacht
jedoch erhöhte Kosten (und wird letztlich ineffizient), wenn der Personenkreis sich
ändert oder die Systembetreuung auf einen anderen Personenkreis übergeht. Letzteres ist typisch der Fall beim Übergang von der Entwicklung zur Nutzung.
Daher müssen auch in Kleinprojekten alle für ein System wichtigen mündlichen In-
4
2 Grundlagen
formationen und Absprachen in Dokumenten festgehalten werden. Mündliche Kommunikation genügt nicht, da Erzeugung und Benutzung von Informationen unter
Umständen um Jahre auseinander liegen können.
●
Sichtbarmachen des Projektfortschritts: Dokumente sind greifbare Resultate
Der Abschluss jeder Phase der Softwareentwicklung wird nachprüfbar markiert
durch die Fertigstellung und Freigabe von Dokumenten. Bei den Produktdokumenten wird stets die Endfassung eines Dokuments erzeugt, welches nur noch über ein
geordnetes Änderungswesen modifizierbar ist. Das Erstellen von Zwischendokumenten nur mit dem Zweck des Nachweises abgeschlossener Tätigkeiten ist zu vermeiden.
Dadurch, dass die Abschlussdokumentation schritthaltend mit der Entwicklung entsteht, ist der Projektfortschritt besser quantifizierbar.
2.1.2 Arten von Dokumentationen
Damit Dokumentationen ihre Aufgaben zufriedenstellend erfüllen können, existieren verschiedene Arten von Dokumentationen. Je nach Art der Dokumentation entstehen sie am
Anfang, während oder gegen Ende des Softwareentwicklungsprozesses.
Generell wird zwischen der Produktdokumentation (Systemdokumentation), die das Softwareprodukt und seine Benutzung dokumentiert, und der Projektdokumentation, die die Entwicklung eines Softwareprodukts dokumentiert, unterschieden [Glinz01].
2.1.2.1 Projektdokumentation
Projektdokumentationen, auch Prozessdokumentation genannt, beschreiben den Prozess der
Entwicklung und Wartung von Softwaresystemen. Sie werden erstellt um das Management
von Softwareentwicklungsprojekten zu unterstützen, indem sie den Projektprozess sichtbar
machen. Ein Hauptmerkmal von Projektdokumentationen ist, dass die meisten mit dem Projektfortschritt veralten [Sommervile01].
Die wichtigsten Arten von Projektdokumenten sind [Glinz01]:
●
Der Projektplan dokumentiert den geplanten Projektablauf, wobei den Soll-Vorgaben
während der Projektabwicklung laufend die Ist-Werte gegenübergestellt werden.
●
Der Qualitätsplan enthält die Vorgaben, die das Projekt betreffend Qualität zu beachten hat. Ist ein standardisierter Rahmen-Qualitätsplan vorhanden, sind projektspezifische Qualitätspläne häufig nicht erforderlich.
●
Das Projektprotokoll enthält alle Schriftstücke und Berichte (z.B. Änderungsanträge,
5
2.1 Software Dokumentation
Review- und Testprotokolle, Fortschrittsberichte, Sitzungsprotokolle), die im Verlauf
der Projektabwicklung anfallen.
2.1.2.2 Produktdokumentation
Produktdokumentationen beschreiben das Softwareprodukt und Entstehen parallel zum
Softwareprodukt, das sie beschreiben. Grundsätzlich werden in Produktdokumentation die
Anforderungen an ein System, das Konzept und die Einzelheiten der Lösung sowie die
Handhabung des Systems dokumentiert. Verwendet werden sie hauptsächlich nach der Fertigstellung des Softwareprodukts, sind aber trotzdem wichtig für das Management der Softwareentwicklung, weil die Fertigstellung solcher Dokumente, zum Beispiel einer Systemspezifikation, als Meilensteine im Entwicklungsprozess angesehen werden können [Sommervile01].
Die wichtigsten Arten von Projektdokumentationen sind [Glinz01][Sommervile01]:
●
●
Systemdokumentationen, beinhalten alle Dokumente, die das System selber beschreiben. Angefangen von den Anforderungsspezifikationen bis hin zu Abnahmevorschriften.
○
Die Anforderungsspezifikation legt präzise, detailliert und soweit wie möglich
nachprüfbar fest, was von dem zu entwickelnden System verlangt wird.
○
Das Lösungskonzept beschreibt die Architektur der Lösung. Dies umfasst insbesondere die Gliederung der Lösung in Komponenten, die Kommunikation zwischen diesen Komponenten, die Verteilung auf Software und Hardware sowie die
Verteilung der Software auf die vorhandenen Ressourcen.
○
Entwürfe und Programmcode beschreiben die Lösungsdetails. Entwürfe werden
entweder separat vom Programmcode dokumentiert oder sie sind in Form von
ausführlichen Kommentaren im Programmcode integriert.
○
Die Testvorschriften legen fest, welche Tests für die einzelnen Komponenten
nach ihrer Fertigstellung durchzuführen sind und welche Tests nach welchem Integrationsschritt auszuführen sind.
○
Der in der Abnahmevorschrift beschriebene Abnahmetest bildet den formalen
Abschluss einer Entwicklung. Der Auftraggeber überprüft mit diesem Test, ob
das System die in der Anforderungsspezifikation gestellten Anforderungen erfüllt.
Benutzerdokumentationen
○
6
Die Installationsanleitung beschreibt, wie ein auf der Zielhardware lauffähiges
2 Grundlagen
System konfiguriert und auf der Zielhardware installiert wird.
○
Das Benutzerhandbuch enthält die Bedienungsanleitung für das System. Es beschreibt aus Benutzersicht, welche Funktionen das System bereitstellt und wie
man es startet und bedient.
Da die Benutzer eines Systems nicht alle identisch sind, sollte die Benutzerdokumentation in verschiedene Teile aufgeteilt werden. Benutzer können sich Aufgrund ihres Fachwissens, ihrer Erfahrung sowie den auszuführenden Tätigkeiten
unterscheiden. Insbesondere ist zwischen Endnutzern einerseits und Entwicklern
und Systemadministratoren andererseits zu unterscheiden.
○
Ein Glossar, welches die verwendeten Begriffe und Abkürzungen erklärt, ist sowohl in der Entwicklung als auch nachher für den Benutzer sehr hilfreich. Ein
solches Glossar sollte daher in jedem grösseren Entwicklungsprojekt erstellt werden.
2.1.3 Problematik von Dokumentationen
Bei der Erstellung von Softwaredokumentationen existieren in der Praxis verschiedene Probleme. Zu den Hauptproblemen gehört erstens, dass Dokumentation für Softwaresysteme
fälschlicherweise oft erst sehr spät oder am Ende des Entwicklungsprozesses erstellt werden. Diese kann dann dazu führen, dass sie unter Zeit und Kostendruck nur unzureichend
oder schlimmstenfalls gar nicht erstellt werden. Zweitens zählt das Erstellen von Dokumentationen unter Entwicklern nicht zu den beliebtesten Aufgaben, was wiederum dazu führen
kann, dass die Aufgabe nicht mit der nötigen Genauigkeit und Sorgfalt durchgeführt wird.
Drittens wird der Dokumentationsprozess oft unterschätzt, denn es ist eine zeitintensive und
keine leichte Aufgabe eine gute Dokumentation zu erstellen. Ebenfalls werden Dokumentationen häufig nicht aktuell gehalten und über die Zeit entstehen immer grössere Unterschiede zwischen der Dokumentation und der tatsächlichen Software.
2.2 Automatische Software Dokumentation
Die automatische Erstellung von Softwaredokumentationen ist für einige Arten von Dokumentationen sehr gut möglich und es existieren viele Werkzeuge, die diese Aufgabe übernehmen oder zumindest erleichtern.
Die Automation oder Teil-Automation des Dokumentations-Prozesses kann in mehreren Bereichen Vorteile bringen und es kann einigen im Kapitel 2.1.3 angesprochenen Problemen
begegnet werden. Durch eine Automation kann der Aufwand für die Erstellung einer Doku-
7
2.2 Automatische Software Dokumentation
mentation verringert werden, woraus dann in weiterer Konsequenz Zeit- und Kostenersparnisse resultieren können. Ebenfalls ermöglichen Werkzeuge die Dokumentation bei Änderungen einfach zu aktualisieren und damit synchron mit der Software zu halten. Dies erhöht,
zusammen mit dem verringertem Aufwand, die Wahrscheinlichkeit, dass Dokumentationen
aktuell gehalten werden. Ein weiterer wichtiger Punkt beim Einsatz von Werkzeugen ist,
dass diese in der Lage sind automatisch zusätzliche Informationen aus dem Softwaresystem
zu extrahieren und in die Dokumentation zu integrieren.
Für Benutzer von automatisch generierten Dokumentationen könnte ebenfalls positiv vermerkt werden, dass die generierten Dokumentationen ein standardisiertes Aussehen besitzen
und sie sich somit leichter zurecht finden, wenn sie damit einmal vertraut sind.
2.3 Dokumentation von Programmcode
Die Dokumentation von Programmcode mittels direkt im Code untergebrachten Kommentaren ist schon seit langem gängige Praxis. Um es aber Werkzeugen zu ermöglichen aus solchen Kommentaren eine separate Dokumentation zu generieren, ist es erstens nötig die
Kommentare speziell auszuzeichnen, damit sie erkannt werden können und zweitens müssen die Kommentare an genau definierten Stellen im Code platziert werden, damit festgelegt
ist welchen Teil des Codes ein Kommentar beschreibt. Ein Werkzeug kann so aus diesen
Kommentaren und zusätzlichen Struktur- und Beziehungsinformationen, die es aus der Analyse des Programmcodes gewinnen kann, eine vollständige Dokumentation erstellen.
2.4 Dokumentation von Datenbanken
Neben den im Kapitel 2.1.1 aufgelisteten Aufgaben, die auch von einer Datenbankdokumentation erfüllt werden müssen existieren weitere Erwartungen an ein Datenbankdokumentation. Diese hängen dabei hauptsächlich vom anvisierten Zielpublikum und dem
Zweck der Dokumentation ab. Unterschiedlich Benutzergruppen haben auch unterschiedliche Anforderungen an eine Dokumentation und benötigen unterschiedliche Informationen
über die Datenbank. Während Endnutzer nur relative oberflächliche aber einfach Verständliche Informationen brauchen, benötigen Entwickler sehr viel detaillierte Informationen und
Datenbankadministratoren können nochmals auf andere sehr spezifische Informationen angewiesen sein. Daneben haben Dokumentationen auch unterschiedliche Verwendungszwecke. Einige Benutzer möchten sie verwenden, um sich einen Überblick über die Datenbank
zu verschaffen, andere benötigen sie um spezifische Details nachzuschlagen.
Die im Bereich der Dokumentation von Programmcode verwendeten Konzepte und Ideen
sind teilweise auch auf den Bereich der Dokumentation von Datenbanken übertragbar. Wie
8
2 Grundlagen
bei der Dokumentation von Programmcode sind auch bei der Dokumentation von Datenbanken einerseits die Kommentare von Codeteilen beziehungsweise hier Datenbankobjekten
und andererseits die Struktur- und Beziehungsinformationen zwischen diesen Objekten
wichtig. Deshalb sollten Dokumentationswerkzeuge die vorhandene Informationen im Datenbankschema möglichst gut nutzen um eine vollständige Dokumentation erstellen zu können. So bringt auch im Bereich von Datenbanken eine Automation des DokumentationsProzesses verschieden Vorteile mit sich. Wenn Dokumentationswerkzeuge automatisch Informationen aus einem Datenbankschema auslesen können, ersparen sie so den Aufwand
diese Informationen manuell in eine Dokumentation mit aufzunehmen. Zusätzlich lässt sich
der Aufwand für die Erstellung einer Dokumentation verringern wenn grosse Teil dieser
Aufgabe durch Werkzeuge übernommen werden. Des weiteren kann der Aufwand, um bei
Änderungen in der Datenbank die Dokumentation zu aktualisieren und synchronisieren auf
ein Minimum reduziert werden. Was die Wahrscheinlichkeit erhöht, dass die Dokumentation
immer aktuell ist und den genauen Zustand der momentanen Datenbank widerspiegelt. All
diese Zusammen kann im Idealfall dann auch zu Zeit- und Kostenersparnissen führen.
9
3 Verwandte Arbeiten
3 Verwandte Arbeiten
3.1 Werkzeuge für die Dokumentation von Programmcode
Werkzeuge zur Dokumentation von Programmcode gibt es viele, einige sind nur für bestimmte Programmiersprachen geeignet, andere sind generischer und können für verschiedene Sprachen eingesetzt werden. Ansonsten sind sich die Werkzeuge in ihrer Funktionsweise sehr ähnlich. Da Java heutzutage eine sehr häufig eingesetzte Programmiersprache ist
und von Sun Microsystems direkt ein Dokumentationswerkzeug namens Javadoc2 mitgeliefert wird, ist dieses Werkzeuge heute sehr bekannt und weit verbreitet. Deshalb und weil die
in dieser Arbeit entwickelte Anwendung in gewissen Bereichen an Javadoc angelehnt ist,
wird im folgenden Unterkapitel genauer auf Javadoc, als Vertreter für die Gruppe dieser
Werkzeuge, eingegangen. Andere bekannte Werkzeuge sind Doxygen3 oder TwinText4, auf
die hier aber nicht weiter eingegangen wird.
3.1.1 Javadoc
Javadoc ist ein Werkzeug, das in Java Quelldateien die Deklarationen von Schnittstellen,
Klassen, Methoden und Feldern sowie Dokumentationskommentare analysiert und daraus
eine Menge von HTML-Seiten generiert, welche diese Elemente dokumentieren. Für jede
Klassendatei wird eine HTML-Seite erstellt, die über verschiedene Querverweise mit anderen Seiten in Verbindung steht. Zusätzlich generiert Javadoc diverse Index- und Hilfsdateien, die das Navigieren in den Dokumentationsdateien erleichtern [SunJavaDoc].
Auch ohne zusätzliche Kommentare erstellt Javadoc aus den Java-Quelldateien eine brauchbare Dokumentation aller Klassen und Schnittstellen. Durch das Einfügen von Dokumentations-Kommentaren kann die Ausgabe aber zusätzlich bereichert werden. Ein Javadoc Kommentar beginnt mit /** und endet mit */ und sieht damit einem gewöhnlichen Kommentar
sehr ähnlich. Er muss im Quelltext immer unmittelbar vor dem zu dokumentierenden Element (Klassen-, Methoden- oder Feld-Definition) platziert werden. Er kann aus mehreren
Zeilen bestehen. Der erste Satz des Kommentars wird später als Kurzbeschreibung verwendet. Zur Erhöhung der Übersichtlichkeit darf am Anfang jeder Zeile ein Sternchen stehen,
welches später ignoriert wird. Innerhalb der Kommentare dürfen neben normalem Text auch
HTML-Tags vorkommen. Sie werden unverändert in die Dokumentation übernommen und
2 http://java.sun.com/j2se/javadoc/
3 http://www.doxygen.org
4 http://www.ptlogica.com
10
3 Verwandte Arbeiten
erlauben es damit, bereits im Quelltext die Formatierung der späteren Dokumentation vorzugeben. Javadoc erkennt des weiteren markierte Absätze innerhalb von Kommentaren so
genannte Tags. Die Tags müssen mit dem Zeichen @ beginnen und abgesehen von Leerzeichen am Anfang einer Zeile stehen. Jeder Tag leitet einen eigenen Abschnitt innerhalb der
Beschreibung ein, alle Tags eines Typs müssen hintereinander stehen [MerkblattJavaDoc].
Ein Javadoc-Kommentar besteht also grundsätzlich aus zwei Teilen, einer Beschreibung gefolgt von einem Tag-Abschnitt. Die Beschreibung endet mit der ersten Zeile, die ein @ enthält. Zwischen der Beschreibung und den Tags sollte eine Leerzeile sein. Jeder JavadocKommentar kann nur einen Beschreibungsblock enthalten. Nach den Tags kann die Beschreibung nicht fortgesetzt werden [EinfJava] [SunJavaDoc].
3.1.1.1 Tags
Javadoc kennt spezielle Annotationen, auch Tags genannt, die in Dokumentationskommentaren eingebettet werden können. Diese Tags ermöglichen es eine besser strukturierte und
formatierte Ausgabe zu erzeugen, indem wichtige Information speziell ausgezeichnet werden können. Zusätzlich ermöglichen sie Links auf andere Element im Programmcode oder
externe Ressource zu setzen, um so in der generierten Dokumentation eine bessere Navigation zu erhalten.
Ein Tag beginnt mit einem @ gefolgt vom Namen des Tags. Für Tag-Namen ist die Grossund Kleinschreibung von Bedeutung. Ein Block-Tag muss am Anfang der Zeile stehen und
kann höchstens von Leerzeichen und einem optionalen *, ansonsten wird es als normaler
Text betrachtet.
Es gibt zwei Arten von Tags: Block-Tags und Inline-Tags. Block-Tags können nur im TagAbschnitt, welcher nach der Beschreibung folgt, verwendet werden. Sie haben die Form:
@tag. Inline-Tags können überall in der Beschreibung oder in Kommentaren von BlockTags eingesetzt werden. Sie müssen von geschwungenen Klammern umgeben werden und
haben die Form: {@tag} [SunJavaDoc].
11
3.1 Werkzeuge für die Dokumentation von Programmcode
Zu den wichtigsten Tags gehören [MerkblattJavaDoc]:
Tag und Parameter
Beschreibung
@author Name
Kann verwendet werden um den Autor eines Elements zu dokumentieren.
@version Version
Kann eingesetzt werden um eine Versionsnummer für Elemente zu führen. Statt einer eigenen Versionsnummer ist es
auch möglich die Versionsnummern von Quellcodeverwaltungssystemen zu verwenden.
@see Referenz
Erzeugt einen Querverweis auf ein anderes Element der Dokumentation. Es gibt drei Arten von Verweisen. Die erste ist
einfacher Text. Die zweite ist eine URL, wie sie in HTML
verwendet wird und die dritte verweist auf andere JavadocElemente. Zusätzlich kann optional noch eine Beschriftung
angegeben werden, die anstelle der Referenz angezeigt wird.
@param Name Beschreibung
Wird verwendet um die Parameter einer Methode zu beschreiben.
@return Beschreibung
Wird verwendet um den Rückgabewert einer Methode zu beschreiben.
@exception Klassenna- Wird verwendet um die Ausnahmen, die von einer Methode
me Beschreibung
geworfen werden, zu dokumentieren.
@deprecated Beschrei- Markiert eine veraltete Methode, die zukünftig nicht mehr
bung
verwendet werden sollte.
Tabelle 1: Javadoc Tags
3.1.1.2 Doclet
Seit Java 1.2 existiert die Möglichkeit über das Konzept der Doclets die Ausgabe von Javadoc den eigenen Bedürfnissen anzupassen. Doclets sind für die Ausgabe der eigentlichen
Dokumentation verantwortlich und bestimmt somit das Aussehen der Dokumentation. Je
nach Programmierung des Doclets kann Javadoc Dokumentationen in den verschiedenen
Formaten generieren. Wenn beim Aufruf von Javadoc keine Doclet angegeben wird, wird
das Java Standard Doclet verwendet, welches eine Ausgabe in HTML erzeugt.
12
3 Verwandte Arbeiten
Um die Ausgabe von Javadoc den eigenen Wünschen anzupassen, muss man nur eigene
Doclets schreiben. Dadurch kann man dann eigene Tags und eigene Kommandozeilenoptionen verarbeiten, als auch andere Ausgabeformate als HTML erzeugen, ohne das man die zu
dokumentierenden Quelldateien ändern muss [SunJavaDoc].
3.2 Werkzeuge für die Dokumentation von Datenbanken
In diesem Unterkapitel werden einige existierende Werkzeuge näher vorgestellt, die automatisch Dokumentationen für Datenbanken erstellen können. Grundsätzlich ist die Arbeitsweise aller Programme sehr ähnlich, sie unterscheiden sich dann aber zum Teil im Funktionsumfang, der Benutzung und den unterstützten Datenbanksystemen. Für ausgewählte Werkzeuge werden deren Möglichkeiten, Besonderheiten und Vor- und Nachteile genauer beschrieben.
3.2.1 DBScribe
DBScribe ist eine von der Firma Leadum Software5 entwickelte Applikation zur Dokumentation von Datenbankenschemas. Es existieren fünf verschiedene Versionen der Software,
von denen jede für ein bestimmtes Datenbanksystem vorgesehen ist. So gibt es Versionen
für Microsoft SQL Server 7 oder neuere Versionen, für Oracle Database 8i oder neuere Versionen, für MySQL Server 3.23 oder neuere Versionen, für IBM DB2 Server 8.2 oder neuere
Versionen und für PostgreSQL Server 7.4 oder neuere Versionen. In weiten Teilen sind sich
diese Versionen sehr ähnlich und unterscheiden sich nur geringfügig in den Möglichkeiten
zur Dokumentation von Datenbankobjekten. Alle Versionen verfügen über eine grafische
Oberfläche, die mit Hilfe von „Wizards“ durch den Prozess der Dokumentationsgenerierung
führen. Daneben besitzen alle Versionen ebenfalls die Möglichkeit das Programm über die
Kommandozeile zu steuern.
Als Ausgabeformate für die Dokumentation werden HTML, HTML-Help und MS Word angeboten. Bei der HTML-Ausgabe ist es möglich zwischen einer ein- oder einer mehrseitigen
HTML-Dokumentation zu wählen. Ebenfalls können für alle Ausgabeformate verschiedene
Stile für die Darstellung, zum Beispiel elegant oder modern, ausgewählt werden. Neben den
eben genannten Möglichkeiten die Ausgabe zu formatieren, gibt es weitere Möglichkeiten
um den Inhalt der Dokumentation zu konfigurieren. DBScribe unterstützt eine grosse Anzahl von Datenbankobjekttypen und bietet für jeden von ihnen eine Vielzahl von Eigenschaften, die dokumentiert werden können. Speziell hervorzuheben ist an diesem Werkzeug,
dass für jeden Datenbankobjekttyp genau festgelegt werden kann, welche Eigenschaften
5 http://www.leadum.com
13
3.2 Werkzeuge für die Dokumentation von Datenbanken
dieses Typs dokumentiert werden sollen und ob die Objekte dieses Typs überhaupt dokumentiert werden sollen. In einer feineren Auswahl kann zusätzlich noch für jedes einzelne
Datenbankobjekt festgelegt werden, ob es in die Dokumentation miteinbezogen werden soll.
Alle Konfigurationseinstellungen können gespeichert werden und erleichtern damit die wiederholte Ausführung.
Je nach Version von DBScribe und damit je nach Datenbankanbindung sind die Datenbankobjekttypen, welche kommentiert werden können, unterschiedlich. Alle Versionen, abgesehen von der Version für PostgreSQL, besitzen ebenfalls die Möglichkeit Kommentare direkt
in DBScribe zu editieren. Trotzdem werden aber auch für PostgreSQL die schon vorhandenen Kommentare ausgelesen und in die Dokumentation übernommen.
Allgemein scheint es, dass in DBScribe den Kommentaren von Datenbankobjekten keine
besondere Stellung in Bezug auf die anderen Eigenschaften der Objekte zukommt, da sie in
der Ausgabe nur als eine unter vielen Eigenschaften eines Datenbankobjekts ausgegeben
werden und nicht besonders abgegrenzt oder gekennzeichnet werden. So hat dann auch die
Dokumentation einen eher technischen Charakter. Trotzdem kann man aber zur Ausgabe positiv vermerken, dass sie sauber strukturiert ist und im mehrseitigen HTML-Format über ein
praktisches Menü verfügt. Dieses Menü besitzt für alle Datenbankobjekttypen einen Eintrag, der auf und zugeklappt werden kann und alle Objekte dieses Typs enthält. Damit erleichtert es die Navigation und erhöht die Übersichtlichkeit der Dokumentation in bedeutendem Masse. Was besonders im Vergleich mit der Navigationsfreundlichkeit mit anderen
Formaten auffällt, wo es einiges umständlicher ist im Dokument zu navigieren. [DBScribe]
3.2.2 SQL Doc
Von der Firma Red Gate Software6 wird die Applikation SQL Doc angeboten. SQL Doc ist
ausschliesslich für die Dokumentation von Microsoft SQL Server Datenbanken geeignet. Es
ist in einer Standard- und einer Professional-Version verfügbar. Die Professional-Version
verfügt zusätzlich über eine Kommandozeilen-Schnittstelle, welche es erlaubt das Programm automatisch zu starten.
SQL Doc ermöglicht es alle im Datenbankschema vorhandenen Objekt einzeln zu dokumentieren und auch Kommentare für alle Objekte zu spezifizieren. Die Kommentare werden
über die von Microsoft SQL Server angebotene Möglichkeit von „Extended Properties“ gespeichert. Für die Benutzerführung bietet SQL Doc eine gute und intuitive grafische Oberfläche. Hilfereich ist auch, dass die erzeugte HTML-Dokumentation sehr ähnlich aussieht
wie die grafische Oberfläche. Dies erleichtert die Orientierung in beiden Teilen.
6 http://www.red-gate.com
14
3 Verwandte Arbeiten
Zu den Vorteilen von SQL Doc zählt, dass mehre Datenbanken gleichzeitig dokumentiert
werden können, wobei auch die Abhängigkeiten zwischen den Objekten aus verschiedenen
Datenbanken aufgezeigt werden. Die grösste Einschränkung ist, dass SQL Doc nur zur Dokumentation von Datenbanken auf Microsoft SQL Server 2000 und SQL Server 2005 fähig
ist. Dies ist möglicherweise auf die Verwendung der proprietären Funktion von „Extended
Properties“ zurückzuführen, die nur in Microsoft SQL Server Datenbanksystemen vorhanden ist. Ein weiterer Nachteil ist, dass als Ausgabeformate nur HTML und HTML-Help zur
Verfügung stehen. [SQLDoc]
3.2.3 SqlSpec
SqlSpec ist ein Datenbankdokumentationswerkzeug von der Firma Elsasoft7. Es bietet sowohl ein grafische Benutzeroberfläche als auch eine sehr umfangreiche KommandozeilenSchnittstelle zur Konfiguration der Applikation. Bemerkenswert ist, dass SqlSpec sehr viele
Datenbanksysteme unterstützt. So können Datenbanken auf Microsoft SQL Server 200,
2005 oder neuere Versionen, Analysis Server 2005, Oracle Database 9i oder neuere, DB2
8.2 oder neuere, Sybase ASE 12.0 oder neuere, Informix IDS 10.0 oder neuere, PostgreSQL
8.0 oder neuere, MySQL 5.0 oder neuere, Access 97 oder neuere, VistaDB 3.0 oder neuere,
ENEA Polyhedra 7.0 oder neuere Versionen dokumentiert werden.
Als Ausgabeformate bietet es dann aber nur HTML oder HTML-Help. Dafür ist die HTMLAusgabe gut gestaltet und mit vielen Grafiken ausgestattet. So können für alle Datenbankobjekte Abhängigkeitsgraphen ausgegeben werden. Die Graphen werden aber im VML
(Vector Markup Language) Format ausgegeben, welches momentan nur der Microsoft Internet-Explorer anzeigen kann.
Ein weiteres spezielles Merkmal von SqlSpec ist, dass für Microsoft SQL Server Datenbanksysteme über „Extended Properties“ Kommentare mit Tags spezifiziert werden können.
Zusätzlich ist es für gespeicherte Prozeduren, benutzerdefinierte Datentypen und Sichten
möglich Kommentare und Tags im SQL-Code dieser Datenbankobjekte zu hinterlegen.
Dazu wird ein spezielles XML-Format verwendet um die Kommentare und Tags auszuzeichnen. Die möglichen Tags bieten aber nur relativ wenig Funktionalität und allgemein
können sie nur für bestimmte Objekte und auch nur bei Microsoft SQL Server Datenbanken
verwendet werden. [SqlSpec]
3.2.4 ApexSQL Doc
Von der Firma ApexSQL LLC8 wird das Dokumentationswerkzeug ApexSQL Doc vertrie7 http://www.elsasoft.org
8 http://www.apexsql.com
15
3.2 Werkzeuge für die Dokumentation von Datenbanken
ben. Dieses Werkzeug verfügt über eine grafische Benutzeroberfläche sowie eine Kommandozeilen-Schnittstelle zur Konfiguration. Wobei die grafische Oberfläche über sehr viele
Optionen verfügt, um genau festlegen zu können, welche Datenbankobjekttypen mit welchen Informationen dokumentiert werden sollen.
Eine grundlegende Einschränkung von ApexSQL Doc ist, dass es nur Datenbanken auf Microsoft SQL Server Datenbanksystemen dokumentieren kann. Dafür ist es in der Lage mehrere Datenbanken gleichzeitig zu dokumentieren. Als Ausgabeformate stehen ebenfalls nur
HTML und HTML-Help zur Verfügung. Aber die HTML-Ausgabe verfügt über ein komfortables Menü zur Navigation und für alle Datenbankobjekte werden Abhängigkeitsgraphen
ausgegeben.
In ApexSQL Doc werden die benutzerdefinierten Kommentare ebenfalls über die Microsoft
SQL Server „Extended Properties“ gespeichert. Zusätzlich gibt es die Möglichkeit Kommentare in SQL-Skripts für diejenigen Datenbankobjekte, für welche der SQL Server die
SQL-Skripts speichert, zu spezifizieren. Speziell an ApexSQL Doc ist, dass es möglich ist in
diesen Kommentaren vordefinierte Tags zu verwenden. Es stehen sechs verschiedene Tags
zur Verfügung: „Summery“, „Remarks“, „Returns“, „Seealso“, „Param“ und „Isnew“. Aber
leider können die meisten dieser Tags nur für Relationen, Sichten, benutzerdefiniert Datentypen, gespeicherte Prozeduren, Trigger, Regeln und Indexes verwendet werden. [ApexSQLDoc]
3.2.5 Zusammenfassende Feststellungen über die Werkzeuge
Neben den hier beschriebenen Werkzeugen existieren noch weitere Werkzeuge zur Dokumentation von Datenbanken, da sie aber alle relative ähnliche Grundfunktionalitäten haben,
wurde darauf verzichtet alle Werkzeuge im Detail zu beschreiben. Weitere Werkzeuge wären unter anderem dbdesc9, SchemaToDoc10, BI Documenter11, SQL Scribe Documentation
Builder12 oder SQL Documentation Tool13.
Als erstes fällt auf, dass viele Werkzeuge nur Microsoft SQL Server Datenbanksysteme unterstützen und es nur sehr wenige gibt, die wirklich viele verschiedene Datenbanksysteme
unterstützen. Ausserdem bieten die meisten Werkzeuge nur HTML und HTML-Help als
Ausgabeformate an oder eventuell noch Microsoft Word oder PDF, aber keine speziellen,
wie zum Beispiel Gegenstands-Beziehungs-Diagramme. Und leider bietet auch keines dieser Werkzeuge eine Möglichkeit neue Datenbankanbindungen oder neue Ausgabeformate zu
9
10
11
12
13
16
http://www.dbdesc.com/
http://www.schematodoc.com/
http://www.bidocumenter.com/Public/Default.aspx
http://www.geckoware.com.au/Content.aspx?Doc_id=1001
http://www.winnershtriangle.com/w/Products.SQLDocumentationTool.asp
3 Verwandte Arbeiten
definieren und hinzuzufügen.
Einige Werkzeuge erlauben die Spezifikation von benutzerdefinierten Kommentaren mit
Tags, doch weisen sie alle sehr viele Einschränkungen diesbezüglich auf. Meistens werden
solche Kommentare mit Tags von Werkzeugen nur in Verbindung mit Microsoft SQL Server
Datenbanksystemen über den „Extended Properties“ Mechanismus unterstützt. Oder nur für
bestimmte Datenbankobjekttypen, für welche SQL-Skripts im Datenbanksystem gespeichert
werden. Ferner sind die von Tags gebotenen Möglichkeiten als relativ einfach zu betrachten.
So existiert beispielsweise selten eine Möglichkeit über Verweise andere Datenbankobjekte
zu referenzieren, besonders nicht um solche Verweise direkt im fliessenden Kommentartext
zu spezifizieren. Ausserdem bietet keines dieser Werkzeuge auch nur ansatzweise eine Unterstützung für die Dokumentation von Datenbankentwurfsmustern.
17
4 Anforderungsspezifikation
4 Anforderungsspezifikation
In diesem Kapitel werden im ersten Teil die allgemeinen Anforderungen, die an eine Software zur automatischen Dokumentation von Datenbanken gestellt werden, beschrieben und
in einem zweiten Teil die speziellen Anforderungen für die im Rahmen dieser Diplomarbeit
erstellten Anwendung spezifiziert.
4.1 Grundlegende Anforderungen
In den folgenden Unterkapiteln werden die wichtigsten Anforderungen detailliert erläutert.
4.1.1 Anbindung unterschiedlicher Datenbanksysteme
Um ein breites Einsatzgebiet für die Anwendung zu erschliessen, ist es essentiell, dass die
Anwendung mit verschiedenen relationalen Datenbanksystemen zusammenarbeiten kann.
Die Anwendung soll deshalb standardmässig die Anbindung von unterschiedlichen relationalen Datenbanksystemen unterstützen sowie ebenfalls die Anbindung von neuen Datenbanksystemen erlauben. Dadurch soll es möglich werden relationale Datenbanken zu dokumentieren, die auf einem beliebigen relationalen Datenbanksystem installiert sind.
4.1.2 Verschiedene Ausgabeformen und Formate
Eine Anwendung zur Dokumentation von Datenbanken muss in der Lage sein eine Datenbank in verschiedenen Formen und Formaten zu dokumentieren. Für die Dokumentation
von Datenbanken können ganz unterschiedliche Formen eingesetzt werden. So können Datenbanken beispielsweise durch Gegenstands-Beziehungs-Diagramme oder durch reine
Textdokumente beschrieben und dokumentiert werden. Deshalb soll die Anwendung verschiedene Formen der Dokumentation anbieten. Weiter soll die Anwendung in der Lage sein
verschiedene Formen der Dokumentation auch in verschiedenen Dateiformaten auszugeben.
So können Gegenstands-Beziehungs-Diagramme als Bilddatei oder als XML-Datei und
Textdokumente können als HTML- oder als PDF-Dokument ausgegeben werden.
Die Anwendung soll deshalb von sich aus schon verschiedene Ausgabeformen und Formate
anbieten, aber zusätzlich sollte sie auch die Erstellung von neuen Ausgabeformen und Formaten ermöglichen. Als standardmässige Ausgabeformate wären da sicher an HTML, PDF
oder auch Microsoft Word beziehungsweise ODF14 zu denken. Des weiteren sind sicher
auch Gegenstands-Beziehungs-Diagramme eine wichtige Form der Dokumentation von Da14 OASIS Open Document Format for Office Applications
18
4 Anforderungsspezifikation
tenbanken.
4.1.3 Unterstützung von Datenbankentwurfsmuster
Von der Anwendung muss ein Mechanismus angeboten werden um die Dokumentation von
Datenbankentwurfsmustern zu unterstützen. Dabei soll für einfache Datenbankentwurfsmuster eine direkte interne Unterstützung angeboten werden und für komplexere Entwurfsmuster soll es eine Möglichkeit geben eine Unterstützung hinzuzufügen. Da Entwurfsmuster
sehr unterschiedlich und komplex sein können, kann es schwierig sein, solche direkt zu unterstützen. Deshalb muss es für Anwender möglich sein durch die Definition von eigenen
Komponenten eine Unterstützung für spezielle Datenbankentwurfsmuster hinzuzufügen. Somit können unterschiedlichste Entwurfsmuster verarbeiten und angemessen dokumentiert
werden.
4.1.4 Kommentare und Annotationen
Um eine gute und ausführliche Dokumentation einer Datenbank erstellen zu können, sind
benutzerdefinierte Kommentare zur Beschreibungen von Datenbankobjekten unerlässlich.
Deshalb muss die Anwendung einige Anforderungen bezüglich benutzerdefinierten Kommentaren erfüllen. Erstens muss es möglich sein alle vorhandenen Datenbankobjekte einzeln
mit einem Kommentar zu versehen. Zweitens sollen Kommentare irgendwo persistent gespeichert werden können, am besten direkt in der Datenbank und in einer standardisierten
Art und Weise, um dann von der Anwendung ausgelesen werden zu können. Drittens soll es
ebenfalls möglich sein Kommentare über die Anwendung zu definieren, zu ändern oder zu
löschen.
Eine weitere sehr wichtige Anforderung für Kommentare ist, dass in Kommentaren auch
Annotationen verwendet werden können. Annotationen bieten die Möglichkeit Metadaten
im Kommentar unterzubringen. Durch solche Metadaten können zum einen verschiedene
Teile eines Kommentars und zum anderen das mit dem Kommentar beschriebene Objekt
speziell ausgezeichnet werden. Deshalb muss die Anwendung in der Lage sein solche Annotationen verarbeiten zu können. Sie soll standardmässig verschiedene Annotationen für verschiedene Zwecke anbieten und genau definieren wie und wo diese Annotationen eingesetzt
werden können. Zusätzlich ist es aber auch wünschenswert, dass der Benutzer eigene Annotationen definieren und verwenden kann.
Allgemein muss es spezielle Annotationen geben um das Aussehen und die Struktur, beziehungsweise die Formatierung eines Kommentars in der Dokumentation, bestimmen zu können. Beispielsweise indem spezielle Information abgegrenzt, versteckt oder hervorgehoben
19
4.1 Grundlegende Anforderungen
werden. Dann muss es Annotationen geben um den Inhalt eines Kommentars an verschiedenen Situationen beziehungsweise Benutzergruppen anpassen zu können. Weiter müssen Annotationen vorhanden sein um im Kommentar eines Datenbankobjekts andere Datenbankobjekte referenzieren zu können, um so Verbindungen zwischen Datenbankobjekten zu schaffen. Als letztes soll es auch noch Annotationen geben mit welchen Metadaten über das Datenbankobjekt selber hinzugefügt werden können, um eine spezielle Behandlung dieser Objekte in der Anwendung zu erlauben. Beispielsweise indem so ausgezeichnete Objekte in
der Dokumentation speziell hervorgehoben oder aber ganz ausgelassen werden.
4.1.5 Flexible Architektur
Zwei Aspekte sind bei der Architektur von besonderer Bedeutung. Erstens muss die Anwendung grundsätzlich über eine flexible Architektur verfügen und zweitens müssen klare
Schnittstellendefinitionen für die einzelnen Komponenten vorhanden sein. Beides zusammen ist notwendig, um eine einfache Erweiterung der Anwendung zu gewährleisten. So soll
es möglich sein einzelne Komponenten der Anwendung zu erweitern, auszutauschen oder
neu zu kombinieren, um so die Funktionalität der Anwendung an verschiedene Gegebenheiten anpassen zu können.
4.1.6 Generisches Datenmodell
Die Anforderung bezüglich des internen Datenmodells sind eher für die Implementierung
wichtig, aber trotzdem entscheidend für eine flexible und erweiterbare Anwendung.
Als Basis für die Anwendung muss ein internes Datenmodell definiert werden. Im Zusammenhang mit dieser Anwendung wird unter dem internem Datenmodell eine Datenstruktur
zur temporären Speicherung von Informationen über eine Datenbank verstanden. Für den
geordneten Zugriff auf die im Datenmodell gespeichert Informationen müssen klare Schnittstellendefinitionen erstellt werden. Und da viele Komponenten mit den Information aus dem
Datenmodell arbeiten müssen, ist es von entscheidender Bedeutung, dass die Schnittstellen
leicht verständlich und gut strukturiert sind sowie sich nicht ändern. Klare Schnittstellendefinitionen im Datenmodell sind ebenfalls für die Erweiterbarkeit und den Austausch von
Komponenten extrem wichtig.
Eine weitere wichtige Anforderung an des Datenmodell ist, dass es möglichst generisch sein
muss. Wodurch es möglich sein soll Informationen über Datenbanken von verschiedensten
Datenbanksystemen zu speichern. Es soll also so allgemein sein, dass es sich für die Anbindung von unterschiedlichen Datenbanksystemen und auch für die Erstellung von verschiedenen Ausgabeformaten eignet.
20
4 Anforderungsspezifikation
4.1.7 Weitere Anforderungen
Weitere, aber weniger zentrale Anforderungen an eine Anwendung zu Dokumentation von
Datenbanken sind: Erstens sollte die Anwendung möglichst benutzerfreundlich sein und zu
diesem Zweck einerseits eine grafische Oberfläche sowie andererseits eine Mechanismus
zur automatischen Ausführung ohne Benutzerinteraktion bereitstellen. Für die automatische
Ausführung muss es deshalb möglich sein alle Konfigurationseinstellungen zu speichern
und die Anwendung über die Kommandozeile zu starten. Zweitens ist es besonders bei der
automatischen Ausführung wichtig, dass die Anwendung auch im Fall von Fehlern oder unerwarteten Vorkommnissen während der Ausführung angemessen reagieren kann und den
Benutzer über die Vorkommnisse detailliert informieren kann. Drittens und letztens muss
die Anwendung in der Lage sein die Dokumentation einer Datenbank in einer angemessenen Zeit zu generieren.
4.2 Spezielle Anforderungen
Für die in Rahmen dieser Diplomarbeit entwickelten Anwendung gelten einige spezielle
Anforderungen. Hauptsächlich weil für die Erstellung der Anwendung nur sehr begrenzte
Ressourcen zur Verfügung stehen. Dies erlaubt es nicht alle gestellten Anforderungen in ihrer ganzen Breite und Tiefe zu implementieren. Dies ist aber auch nicht das Ziel, sondern es
sollen Lösungsvorschläge für die grundlegenden Probleme entwickelt und die Machbarkeit
und Eignung anhand einer Implementierung aufgezeigt werden.
Für die Implementierung der Anwendung soll als Programmiersprache ausschliesslich Java
in der Version 1.5 eingesetzt werden. Für die Anbindung von Datenbanksystemen soll es
grundsätzlich möglich sein unterschiedliche Datenbanksysteme zu unterstützen und es muss
mindestens eine Datenbankanbindung für die Anbindung von PostgreSQL Datenbanksystemen implementiert werden. Für die Ausgabe der Dokumentation bestehen ähnliche Anforderungen. So sollen grundsätzlich verschiedene Ausgabeformate möglich sein und es muss
mindestens die Ausgabe einer Dokumentation im HTML-Format implementiert werden.
Um die Möglichkeiten der Anwendung zur Unterstützung von Datenbankentwurfsmuster zu
zeigen, sollen verschiedene Entwurfsmuster, die in der sesamDB zum Einsatz kommen, unterstützt werden.
21
5 Design
5 Design
Um die im vorhergehenden Kapitel gestellten Anforderung an die Anwendung erfüllen zu
können, wurden verschieden Konzepte entwickelt, die in diesem Kapitel beschrieben werden. Aus den Anforderungen geht hervor, dass beim Design besonderen Wert auf die Erweiterbarkeit und Flexibilität gelegt werden muss. Zu den wichtigsten Designkriterien zählt
deshalb die Erweiterbarkeit, die Flexibilität sowie die Wiederverwendung von einzelnen
Komponenten und eine klare Definition der Schnittstellen zwischen den einzelnen Komponenten.
In den folgenden Unterkapiteln wird jeweils auf einen Teilaspekt des Designs eingegangen.
Wobei zuerst das Design des internen Datenmodells, anschliessend die Plug-in Architektur
mit den verschiedenen Plug-in Typen und zum Schluss noch das Design für Kommentare
und Annotationen beschrieben wird.
5.1 Datenmodell
Die meisten Komponenten einer Anwendung zur Dokumentation von Datenbanken müssen
in irgendeiner Form mit Informationen über eine Datenbank arbeiten. Komponenten zum
Einlesen von Informationen aus einer Datenbank müssen diese Information irgendwo temporär speichern können damit andere Komponenten später darauf zugreifen können. Komponenten zur Ausgabe der Dokumentation müssen irgendwo die Information über die Datenbank beziehen können und zwischen diesen Phasen sollten weitere Komponenten solche
Informationen auch verändern und anpassen können.
Für die Anwendung ist deshalb die Definition eines internen Datenmodells, zur temporären
Speicherung der Informationen über die Datenbank, von zentraler Bedeutung. Bei diesen Informationen handelt es sich vorwiegend um Information über in der Datenbank vorhandene
Datenbankobjekte. So werden mit dem Datenmodell diese Datenbankobjekte, ihre Struktur
und ihre Beziehungen beschrieben. Konkret werden Datenbankobjekte durch Schnittstellen
beschrieben. Diese Schnittstellen spezifizieren die Eigenschaften und die Beziehungen von
Datenbankobjekten und ermöglichen den Zugang zu diesen Informationen. Eine klare Definition der Schnittstellen ist wichtig, weil sich andere Komponenten darauf verlassen müssen, wenn sie mit Information über Datenbankobjekte arbeiten wollen.
Beim Design des Datenmodells musste auf verschiedene Punkte bezüglich der Flexibilität
und der Allgemeingültigkeit des Modells geachtet werden. Zum einen soll das Datenmodell
so allgemeingültig sein, dass darin Informationen über Datenbankobjekte aus unterschiedli22
5 Design
chen Datenbanksystemen gespeichert werden können, um so eine Anbindung von unterschiedlichen Datenbanksystemen zu ermöglichen. Zum anderen sollen die im Datenmodell
gespeicherten Informationen so allgemein repräsentiert werden, dass sich daraus verschiedene Ausgaben generieren lassen.
5.1.1 Schnittstellenhierarchie
Wie schon angesprochen handelt es sich bei den Informationen über eine Datenbank hauptsächlich um Informationen über Datenbankobjekte. In einer Datenbank existieren viele verschiedene Arten von Datenbankobjekten. Objekte einer Datenbank sind unter anderem
Schemas, Relationen, Sichten, Spalten, Datentypen, Indexes, Einschränkungen oder Trigger.
Um im Datenmodell die verschiedenen Typen von Datenbankobjekten zu repräsentieren,
wurde für jeden Typ eine eigene Schnittstelle entwickelt. Zusätzlich wurde für die generische Repräsentation von Datenbankobjekten eine übergeordnete Schnittstelle erstellt, welche die Eigenschaften beschreibt, die allen Datenbankobjekten gemeinsam sind. Das Ergebnis dieses Designschrittes ist eine Schnittstellenhierarchie, in welcher alle Schnittstellen zu
Datenbankobjekten definiert werden. Weil diese Schnittstellenhierarchie mit 26 Schnittstellen zur Beschreibung von Datenbankobjekten sehr umfangreich ist, wird in Abbildung 1 nur
ein Ausschnitt der Schnittstellenhierarchie mit einigen zentralen Schnittstellen dargestellt.
23
5.1 Datenmodell
24
5 Design
Abbildung 1: Ausschnitt aus der Schnittstellenhierarchie
25
5.1 Datenmodell
Zuoberst in der Hierarchie befindet sich die Schnittstelle DBObjectInfo. Diese Schnittstelle abstrahiert vom konkreten Typ eines Datenbankobjekts und repräsentiert damit generisch ein beliebiges Datenbankobjekt. Von dieser allgemeinen Schnittstelle erben andere
Schnittstellen, um sie zu erweitern und spezifische Eigenschaften von Datenbankobjekttypen zu repräsentieren. So erbt die Schnittstelle OwnedDBObjectInfo von DBObjectInfo. Diese repräsentiert generell ein Datenbankobjekttyp, welcher einen Besitzer hat. Der
Besitzer eines Datenbankobjekts ist ein Datenbankbenutzer, welcher über spezielle Rechte
für dieses Datenbankobjekt verfügt. Von der Schnittstelle OwnedDBObjectInfo erben
weiter Schnittstellen, wie zum Beispiel RelationInfo, welche Datenbankobjekttypen repräsentiert, die eine „tabellenartige“ Struktur haben, wie Relationen und Sichten. Deshalb
erben von RelationInfo die Schnittstellen TableInfo und ViewInfo, welche konkrete Datenbankobjekttypen, nämlich eine Relation beziehungsweise eine Sicht beschreiben. Neben diesen Schnittstellen existieren noch viele weitere Schnittstellen, je eine pro Datenbankobjekttyp.
Noch wichtig zu erwähnen ist, dass die Schnittstelle DBObjectInfo von der Schnittstelle
Comparable erbt. Dadurch wird es möglich, beliebige Datenbankobjekt miteinander zu
vergleichen und in weiterer Konsequenz auch zu sortieren. Datenbankobjekte werden in erster Instanz alphabetisch anhand ihres Typs und in zweiter Instanz alphabetisch anhand ihres
vollen Namens sortiert. Nur für Spalten wurde geringfügig davon abgewichen. Und zwar
werden Spalten, die sich in der selben Relation oder Sicht befinden, nicht nach ihrem Spaltennamen sondern nach ihrer Spaltennummer sortiert. Die Entscheidung alle Datenbankobjekttypen die Schnittstelle Comparable implementieren zu lassen, wurde getroffen, weil,
wenn in anderen Komponenten mit Mengen oder Sets von Datenbankobjekten gearbeitet
werden muss, diese immer schon sortiert sind und die Arbeit dadurch erleichtert wird.
Zusätzlich zu den Schnittstellen für Datenbankobjekttypen wurde noch eine Schnittstelle namens RootInfo erstellt, welche den zentralen Zugangspunkt zum Datenmodell darstellt.
Über diese Schnittstelle ist es möglich auf alle vorhandenen Datenbankobjekte zuzugreifen.
Sie bietet Methoden um alle Datenbankobjekte eines Typs zu erhalten oder auch um bestimmte Datenbankobjekt aufgrund von bestimmten Eigenschaften zu suchen.
Für das Design des Datenmodells wurde eine Schnittstellenhierarchie einer Klassenhierarchie vorgezogen, da diese generischer und flexibler ist. Durch diese Wahl bleibt die Implementierung des Datenmodells austauschbar, weil andere Komponenten nicht spezielle Klassen sondern Schnittstellen referenzieren.
26
5 Design
5.1.2 Erzeugung der Objekte
Um nicht nur bei der Repräsentation der Datenbankobjekte sondern auch bei deren Erzeugung zu abstrahieren und somit von ihrer Implementierung unabhängig zu sein, wurde ein
Entwurfsmuster, das unter dem Namen „Abstrakte Fabrik“ bekannt ist, eingesetzt. Die Abstrakte Fabrik gehört zur Gruppe der objektbasierten Erzeugungsmustern und bietet eine
Schnittstelle zum Erzeugen von Objekten, ohne ihre konkreten Klassen zu benennen [Gamma04].
Das Entwurfsmuster besteht aus den Teilen:
●
Abstrakte Fabrik, in diesem Fall die Schnittstelle DBObjectFactory. Sie deklariert eine abstrakte Schnittstelle für Methoden, die konkrete Produktobjekte erzeugen.
●
Konkrete Fabrik, hier die Klasse POJOFactory, welche die Methoden zur Erzeugung konkreter Produktobjekte implementiert.
●
Abstrakte Produkte sind hier die Schnittstellen der einzelnen Datenbankobjekte.
Zum Beispiel TableInfo oder ColumnInfo.
●
Konkrete Produkte sind hier die Klassen, welche die Schnittstellen implementieren.
Zum Beispiel TableImpl oder ColumnImpl.
●
Klienten, sind hier die alle Komponente, die Datenbankobjekte erzeugen möchten.
Sie verwenden nur die Schnittstellen von der abstrakten Fabrik und von den abstrakten Produkten ohne ihre konkreten Implementierungen kennen zu müssen.
5.1.3 Namen und Referenzierung
Alle Schnittstellen von Datenbankobjekttypen besitzen Methoden um verschiedene Eigenschaften von Objekten zu setzen und sie dann auch wieder auszulesen. Nur der Name eines
Datenbankobjekts kann nicht verändert werden. Der Name wird bei der Erzeugung des Objekts spezifiziert und kann dann nicht mehr geändert werden. Wie nachfolgend erklärt wird
ist dies nötig, weil Datenbankobjekte häufig anhand ihres Namens und nicht ihrer ObjektReferenz referenziert werden.
Bei den Methoden von Datenbankobjekttypen wird generell zwischen Methoden unterscheiden, welche einfache Werte, wie Zahlen oder Text, setzen und lesen und Methoden, welche
Referenzen auf andere Datenbankobjekte setzen und lesen. Bei Methoden die Referenzen
auf andere Datenbankobjekte setzten werden die Referenzen in Form einer einfachen Zeichenfolge, die den Namen des zu referenzierenden Objekts enthält übergeben.
27
5.1 Datenmodell
Beim Namen eines Datenbankobjekts handelt es sich um den SQL-Namen des Datenbankobjekts wie er in der Datenbank definiert und verwendet wird, also den selben Namen den
man auch in Datenbankanfragen verwenden würde, um auf das Objekt zuzugreifen. Der
Name eines Datenbankobjekts kann, wie im SQL-Standard definiert, aus mehreren Teilen
bestehen. Je nachdem auf welcher Ebene die Namen von Datenbankobjekttypen eindeutig
sind, müssen sie unterumständen mit dem Namen eines Schemas oder eines Schemas und
einer Relation qualifiziert werden, damit der Name über alle Datenbankobjekte eindeutig ist.
Im folgenden wird deshalb zwischen dem einfachen und dem voll qualifizierten Namen von
Datenbankobjekten unterschieden.
Wenn die Methode einen bestimmten Typ eines Datenbankobjektes erwartet, kann entweder
der qualifizierte oder der einfache Namen des Datenbankobjekts übergeben werden. Der
einfache Namen kann aber nur solange verwendet werden, wie der einfache Name über alle
Datenbankobjekt dieses Typs eindeutig ist, ansonsten muss der qualifizierte Namen übergeben werden. Erwartet die Methode keinen bestimmten Typ, das heisst es können beliebige
Datenbankobjekte übergeben werden dann kann es nötig sein zusätzlich noch den Typ des
Datenbankobjekts dem qualifizierten Namen voran zustellen. Die Kombination dieser zwei
Informationen ist notwendig, da die voll qualifizierten Namen von Datenbankobjekten zwar
eindeutig sind innerhalb des gleichen Typs, aber es ist möglich, dass ein Datenbankobjekt
von einem anderen Typ mit dem selben voll qualifizierten Namen existiert. Zur eindeutige
Identifikation eines Datenbankobjekte dient deshalb der Typ das Datenbankobjekts sowie
der voll qualifizierte Namen des Datenbankobjekts.
5.1.4 Verlinkung
Da in den Datenbankobjekten bei den Methoden zum Setzen von Referenzen nur Namen
übergeben werden, ist es in einem späteren Schritt notwendig alle diese Referenzen aufzulösen und die tatsächlichen Objekt-Referenzen in den Datenbankobjekten zu speichern. Dies
geschieht nachdem alle Datenbankobjekte erzeugt wurden. Das RootInfo-Objekt verfügt
über Objekt-Referenzen auf alle Objekte, da alle Objekte direkt bei ihrer Erzeugung dort registriert werden und deshalb ist es in der Lage alle Objekte zu verlinken. Nachdem alle Objekte verlinkt sind können andere Komponenten ganz normal mit den Objekt-Referenzen arbeiten und brauchen sich keine Gedanken mehr über die Namen zu machen.
Anstatt der Angabe von einfachen Zeichenfolgen bei den Methoden um Referenzen auf anderer Datenbankobjekte zu setzen, wäre es auch möglich gewesen direkt die Referenzen auf
Objekte anzugeben. Der Vorteil wäre, dass keine separate Verlinkung der Objekte nötig
28
5 Design
wäre und ebenfalls sichergestellt wäre, dass keine unbekannten Referenzen gesetzt werden
könnten. Dies würde die Implementierung des Datenmodells erheblich vereinfachen, da die
Objekte dann wirklich nur noch einfache Java-Objekte mit Instanzvariablen und zugehörigen Methoden zum Setzen und Holen der Werte dieser Instanzvariablen.
Der grosse Nachteil dieser Variante käme aber bei der Implementierung einer Einlese-Komponente zum Vorschein. Eine Einlese-Komponente bezeichnet hier eine Komponente mit
der Informationen aus der Datenbank eingelesen werden. Dort müsste viel mehr Aufwand
betrieben werden, um die verschiedenen Datenbankobjekte korrekt zu erzeugen.
Es macht aber mehr Sinn diesen Aufwand in der Modell-Komponente zu betreiben, als in
der Einlese-Komponente, denn Einlese-Komponenten wird es mehrere geben, während es
nur eine Modell-Komponente geben wird. Dies vereinfacht die Erstellung von neuen Einlese-Komponenten massiv und damit die Wahrscheinlichkeit, dass zusätzliche Einlese-Komponenten für verschiedene Datenbanksysteme entwickelt werden.
Denn bei der Reihenfolge der Erzeugung und dem Setzten von Eigenschaften der Objekte
müsste genau auf die Abhängigkeiten zwischen den Objekten Rücksicht genommen werden.
Da aber viele Objekte sich gegenseitig referenzieren führt nicht einmal die strikte Einhaltung der Reihenfolge beim Erzeugen der Objekte zum Ziel, denn wenn sich zwei Objekte
sich gegenseitig referenzieren ist es nicht möglich zu entscheiden welches Objekte zuerst erstellt und dessen Eigenschaften gesetzt werden sollten. Denn beim setzen der Eigenschaften
braucht man schon die Referenz auf das andere Objekt. So wäre die einfachste Lösung für
die Einlese-Komponente nur zuerst alle Datenbankobjekte zu erzeugen und danach wenn
alle Referenzen vorhanden sind für jedes Objekt dessen Eigenschaften zu setzen. Diese führt
aber zu einem erheblich grösseren Aufwand in der Einlese-Komponente, weil alle Referenzen auf erzeugte Objekte gespeichert werden müssten um wieder auf sie zugreifen zu können. Oder die Referenzen können auch im Datenmodell gespeichert werden, damit dieser
Aufwand entfällt, aber trotzdem müssten viele Datenbankobjekt mehrmals verändert werden
um alle Eigenschaften vollständig zu konfigurieren.
Hingegen erlaubt der hier gewählte Ansatz der Einlese-Komponente sich mit jedem Datenbankobjekte nur ein einziges mal zu beschäftigen. Das heisst ein Datenbankobjekt kann erzeugt werden und gleich danach vollständig konfiguriert indem alle Eigenschaften gesetzt
werden können. Dies wird ermöglicht indem Beziehungen zu anderen Objekten nicht direkt
über die Objekt-Referenzen gesetzt werden müssen sondern nur über die Angabe des Namen des zu referenzierendem Objekt. So können Referenzen auf andere Objekte gesetzt
werden die zum diesem Zeitpunkt noch gar nicht existieren.
Natürlich ist es nötig das am Ende des Einlese-Prozesses alle Datenbankobjekte auf welche
29
5.1 Datenmodell
Referenzen existieren erzeugt wurden ansonsten wird das Modell nicht in der Lage sein alle
Referenzen aufzulösen und es würden Fehlmeldungen für die nicht existierenden Objekte
ausgegeben.
5.2 Plug-in Architektur
Wie im Kapitel über die Anforderungen beschrieben, wird für die Gesamtarchitektur eine
Lösung gesucht, welche flexibel und erweiterbar ist. Ebenso soll die Anwendung verschiedene Datenbankanbindungen, Ausgabeformate und Möglichkeiten zur Unterstützung von
Datenbankentwurfsmustern anbieten können. Diese funktional verschiedenen Bereiche der
Anwendung eignen sich hervorragend um die Anwendung entsprechend in verschiedene
Komponenten zu unterteilen.
So wurden als erstes einzelne Komponenten aufgrund ihrer Zuständigkeiten identifiziert und
definiert. Es entstand eine Aufteilung der Anwendung in vier Komponenten. Eine Komponente ist für die Datenbankanbindung und damit für das Einlesen der Daten verantwortlich.
Eine weitere Komponente ist für die Ausgabe der Daten und somit für die Generierung der
eigentlichen Dokumentation zuständig. Eine dritte Komponente soll eine allgemeine Transformation der Daten erlauben und dadurch unter anderem ermöglichen Datenbankentwurfsmuster zu unterstützen. Die letzte Komponente schliesslich ist für die Realisierung des Datenmodells verantwortlich. Dieses Datenmodell wird von den anderen drei Komponenten
verwendet um dort einerseits die eingelesenen Daten zu speichern und andererseits um zur
Weiterverarbeitung wieder auf die Daten zugreifen zu können.
In einen zweiten Schritt wurde festgelegt, dass es verschiedene Varianten der einzelnen
Komponenten geben kann um so verschiedene Datenbankanbindungen, verschiedene Ausgaben, verschiedene Transformationen und verschiedene Implementierungen des Datenmodells zu ermöglichen. Wenn es verschiedene Varianten einer Komponenten gibt, kann der
Funktionsumfang einer Variante auf ein bestimmtes Gebiet beschränkt werden. Zum Beispiel kann es für die Eingabe-Komponente eine Variante geben, die für die Anbindung von
PostgreSQL Datenbanksystemen verantwortlich ist und eine Variante, die für die Anbindung
von Microsoft SQL Server Datenbanksystemen verantwortlich ist. Oder bei der AusgabeKomponente kann es eine Variante geben, die Dokumentationen im HTML-Format erstellt
und eine andere Variante, die Dokumentationen im PDF-Format erstellt. Der offensichtliche
Vorteil von verschiedenen Varianten einer Komponente ist, dass eine Variante einen genau
definierten Umfang hat und dadurch leichter zu verstehen und ebenfalls einfacher zu implementieren ist.
Die Herausforderung beim Entwurf der Anwendung bestand nun darin eine Möglichkeit zu
30
5 Design
finden um den Umstand von verschiedenen Komponenten und verschiedenen Varianten von
diesen Komponenten im Design widerzuspiegeln. Sowie eine Architektur zu finden, die es
der Anwendung ermöglicht verschiedene Varianten von Komponenten flexibel zu kombinieren, um so ihre Aufgabe zu erfüllen. So wurde angelehnt an die Konzepte von [PluginArch] eine so genannte Plug-in Architektur entwickelt. Unter einem Plug-in verstehen wir
hier eine Variante einer Komponente. Die Plug-in Architektur soll es der Anwendung ermöglichen ihre Funktionalität durch eine geeignete Kombination von Plug-ins zu erreichen.
Und die Anwendung kann einfach an verschiedene Gegebenheiten angepasst werden indem
Plug-ins hinzugefügt, entfernt oder ausgetauscht werden.
Die Plug-in Architektur besteht grundsätzlich aus einem Plug-in Manager und den einzelnen
Plug-ins. Damit der Plug-in Manager mit verschiedenen Plug-ins zusammenzuarbeiten, beziehungsweise diese verwenden kann, ist es notwendig, dass Plug-ins über einheitliche
Schnittstellen verfügen, auf die sich der Plug-in Manager verlassen kann. Deshalb wurde ein
allgemeines Java Interface erstellt, das die grundlegende Schnittstelle eines Plug-ins beschreibt. Analog zu den vier zuvor identifizierten Komponenten der Anwendung wurden
vier Plug-in Typen definiert und für jeden Typ wurde ein Java Interface spezifiziert. Diese
Interfaces sind Untertypen des allgemeinen Plug-ins.
Abbildung 2: Plug-in Typen
31
5.2 Plug-in Architektur
Wie in Abbildung 2 zu erkennen ist, gibt es eine Schnittstelle namens DBDocPlugin, welches die allgemeine Schnittstelle eines Plug-ins und dessen Grundfunktionen beschreibt.
Von diesem wurde dann für jeden Typ von Plug-in eine Schnittstelle abgeleitet, welche die
speziellen Funktionen des Plug-in Typs spezifiziert.
Jedes Plug-in kennt die Methoden:
●
name()
Gibt den den Namen des Plug-ins zurück.
●
usage()
Gibt einen kurzen Text zurück, welcher Hinweise über die korrekte Verwendung sowie möglichen Optionen des Plug-ins enthält.
●
initialize(reporter : PluginReporter)
Initialisiert das Plug-in und sollte deshalb bei einem neue erstellten Plug-in als erstes
aufgerufen werden. Ebenfalls übergibt es ihm einen PluginReporter zur Meldung von Statusinformationen.
●
setupOptions(options : Map<String, String>)
Damit können dem Plug-in spezifische Optionen, in der Form von Schlüssel-Werte
Paaren, zur Konfiguration übergeben werden.
Die Methoden initialize() und setupOptions() können beide auch eine PluginException
werfen, um dem Plug-in Manager eine Ausnahmesituation zu melden.
Das Ziel der Plug-in Architektur ist, dass es einfach und ohne Änderungen in der Anwendung möglich ist Plug-ins auszutauschen, neue hinzuzufügen oder sie anders zu kombinieren. Dies ist möglich, da der Plug-in Manager, welcher für die Verwaltung der Plug-ins verantwortlich ist, sich auf die Plug-in Schnittstellen verlassen kann, um die benötigten Methoden der Plug-ins aufzurufen. Und zusätzlich werden ihm über Konfigurationsangaben die
Klassennamen der Plug-ins bekannt gegeben. So kann der Plug-in Manager die Klassen dynamisch laden und danach gemäss ihrer Plug-in Schnittstelle verwenden. Durch diese Architektur werden nirgends im Code Klassennamen von Plug-in direkt codiert, sondern die
Namen der Klassen werden dem Plug-in Manager zur Laufzeit übergeben und erst dann
werden die Klassen dynamisch geladen. Neben dem Namen der Klasse benötigt der Plug-in
Manager noch weitere Angaben. Er muss wissen in welcher Reihenfolge die Plug-ins auszuführen sind. Dies geschieht mit einer einfachen Zahl. Die Zahlen müssen dabei nicht fortlau32
5 Design
fend sein. Der Plug-in Manager führt einfach das Plug-in mit der kleinsten Zahl zuerst aus
und dann der Reihe nach alle anderen. Zusätzlich muss der Plug-in Manager ebenfalls über
alle Optionen der einzelnen Plug-ins verfügen, damit er sie den Plug-ins nachdem initialisieren übergeben kann. Um für die Anwendung zu spezifizieren, welche Plug-ins mit welchen
Optionen ausgeführt werden sollten, gibt es zwei Möglichkeiten. Zum einen können Plugins und ihre Optionen auf der Kommandozeile und zum anderen in einer speziellen XMLDatei spezifiziert werden. Diese beiden Möglichkeiten werden im Kapitel 6 näher beschrieben.
5.2.1 Model-Plug-in
Ein Model-Plug-in ist allgemein gesagt eine Komponente, welche das Datenmodell implementiert. Das Datenmodell ist eine zentrale Schnittstellenhierarchie, die unabhängig von der
Plug-in Architektur definiert wurde. Und obwohl das Datenmodell selber nicht geändert
werden kann, so kann doch die Implementierung geändert werden. Deshalb wurde entschieden die Implementierung des Datenmodells ebenfalls als Plug-in zu definieren, um so die
Implementierung des Datenmodells einfach austauschbar zu machen.
Über die Methoden provideRootInfo() stellt das Plug-in eine so genanntes RootInfo-Objekt zur Verfügung, welches als Hauptzugangspunkt auf das Datenmodell fungiert und somit
den Zugriff auf alle Informationen über die Datenbank ermöglicht.
Die Methode linkAllDBObjectInfos(rootinfo : RootInfo) übernimmt nach dem Einlesen und
Erstellen aller Datenbankobjekte die Verlinkung dieser Objekte in dem übergebenen RootInfo-Objekt.
5.2.2 Input-Plug-in
Ein Input-Plug-in ist eine Komponente, die zur Anbindung eines Datenbanksystems dient.
Ein Input-Plug-in kann eine Verbindung zu einem Datenbanksystem aufnehmen, um dann
Informationen über eine Datenbank auszulesen. Es kann über den Zugriff auf Schema-Informationen, Informationen über vorhandene Datenbankobjekte gewinnen und mit diesen Informationen und unter zur Hilfenahme des RootInfo-Objektes kann das Input-Plug-in
dann die entsprechenden Datenbankobjekte erstellen, um die Informationen für die spätere
Verarbeitung zu speichern. Zu diesem Zweck besitzt ein Input-Plug-in die Methode readInput(rootinfo : RootInfo).
5.2.3 Output-Plug-in
Ein Output-Plug-in ist eine Komponente, welche die im Datenmodell beziehungsweise im
33
5.2 Plug-in Architektur
RootInfo-Objekt vorhandenen Informationen ausgeben kann und somit die eigentliche
Dokumentation der Datenbank erstellt. Wie angesprochen kann es sehr verschiedene Output-Plug-ins geben.
Eine HTML-Ausgabe wurde gewählt, weil es eine sehr benutzerfreundliches Format ist. Einerseits können HTML-Seiten plattformunabhängig auf allen Computersystemen angesehen
werden. Andererseits ist HTML sehr gut für die Benutzerführung geeignet, da Verlinkungen
zur Verfügung stehen, dies im Gegensatz zu MS Word oder PDF Dokumenten wo nur eine
sehr eingeschränkte Verlinkung möglich ist. Ebenfalls eignen sich HTML-Dokumente bestens für die Veröffentlichung der Dokumentation über Inter- oder Intranet. Beim Design und
der Implementierung der HTML-Ausgabe war es wichtig ein optisch ansprechendes Ergebnis zu produzieren sowie eine komfortable Navigation zur Verfügung zu stellen.
5.2.4 Transformator-Plug-in
Ein Transformator-Plug-in ist eine Komponente, welche die Informationen im Datenmodell
beziehungsweise die Datenbankobjekte im RootInfo-Objekt in irgendeiner Weise verändert. Sei es indem bestimmte Eigenschaftswerte von Datenbankobjekten geändert werden,
neue Eigenschaften zu Datenbankobjekten hinzugefügt werden oder Datenbankobjekte ganz
neu erzeugt werden. Die Schnittstelle von Transformator-Plug-ins wurde bewusst sehr allgemein gehalten, womit erreicht wird, dass Transformator-Plug-ins für ganz verschiedene
Zwecke eingesetzt werden können. Sie können verwendet werden, um fehlenden Informationen, wie Eigenschaften oder Kommentare, zu bestimmten Datenbankobjekten hinzuzufügen. Dies kann nützlich sein, wenn gewisse Information in der Datenbank nicht vorhanden
sind oder wenn bestimmte Aspekte besonderes dokumentiert werden sollen. Ebenfalls ermöglichen Transformator-Plug-in die im RootInfo-Objekt vorhandenen Datenbankobjekt zu filtern, um unerwünschte Objekte aus der Dokumentation auszuschliessen. Dies kann
nötig sein, wenn man datenbanksystemspezifische Objekte nicht dokumentieren möchte
oder wenn man Dokumentationen für bestimmte Benutzergruppen erstellt und den Detailgehalt der Dokumentation anpassen möchte.
Der angedachte Hauptverwendungszweck für Transformator-Plug-ins ist aber die Unterstützung von Datenbankentwurfsmustern. Weil Datenbankentwurfsmuster sehr unterschiedlich
sein können und auch die Art und Weise der Dokumentation von Entwurfsmuster sehr unterschiedlich ausfallen könnte, ist es schwierig ein allgemeines Transformator-Plug-in zu erstellen.
Die Schnittstelle eines Transformator-Plug-ins besitzt gegenüber einem abstrakten Plug-in
ebenfalls nur eine zusätzliche Methode. Es ist die Methode transform(rootinfo : RootInfo).
34
5 Design
5.2.5 Plug-in Manager
Der Plug-in Manager ist jener Teil der Anwendung, welcher die Verwaltung der Plug-ins
übernimmt. Er ist verantwortlich für die Initialisierung, Konfiguration und Ausführung der
Plug-ins. Wobei er selber auf Konfigurationsangaben zurückgreift, um allen Plug-ins ihre
Optionen zu übergeben und sie in der richtigen Reihenfolge auszuführen.
5.3 Kommentare und Annotationen
Beim Design der Komponenten für die Unterstützung von benutzerdefinierten Kommentaren für Datenbankobjekte und Annotationen mussten einerseits die Anforderungen aus Kapitel 4.1.4 erfüllt werden und andererseits mussten weitere Ideen entwickelt werden, wie benutzerdefinierte Kommentare und Annotationen angemessen unterstützt werden können. In
gewissen Bereichen diente auch Javadoc als Inspiration für neue Ideen und mögliche Lösungen.
5.3.1 Speicherung
Eine Entscheidung bezüglich benutzerdefinierten Kommentaren für Datenbankobjekte war,
wie und wo solche Kommentare gespeichert werden sollten, damit sie von der Anwendung
ausgelesen werden können. Für die Spezifikation und Speicherung sowie den Zugriff auf
Kommentare sind mehrere Möglichkeiten denkbar. Eine unbefriedigende Lösung wäre,
wenn Kommentare von Benutzer nur über die Anwendung selber spezifiziert werden könnten und die Anwendung für die Speicherung verantwortlich wäre. Bei einer solchen Lösung
würden die Kommentare aber ausserhalb der Datenbank und damit völlig unabhängig von
den eigentlichen Datenbankobjekten gespeichert. Was dazu führen kann, dass Kommentare
nicht mehr mit dem Zustand der Datenbank übereinstimmen, falls sich Änderungen in der
Datenbank ergeben. Ausserdem ist eine solche Lösung höchst proprietär, denn nur diese Anwendung kann auf die Kommentare zugreifen und sie ändern. Eine andere Möglichkeit zur
Speicherung von Kommentaren wäre die Unterbringung als SQL-Kommentar in SQL Skripten. Dies ist aber nur möglich für Datenbankobjekt, die durch ein SQL Skript definiert werden und wenn diese SQL Skripts auch vom Datenbanksystem gespeichert werden. Für alle
anderen Datenbankobjekte wäre es nicht möglich Kommentare zu spezifizieren und zu speichern. Aber immerhin wäre ein Kommentar zusammen mit dem zugehörigen Datenbankobjekt in der Datenbank gespeichert. Und durch Zugriff auf die Datenbank können die Kommentare auch von beliebigen Anwendungen ausgelesen werden. Eine weitere Möglichkeit
wäre die Nutzung einer vom Datenbanksystem angebotener proprietären Funktion zur Do35
5.3 Kommentare und Annotationen
kumentation. Denn einige Datenbanksysteme bieten eigene Funktionen, um Datenbankobjekte zu kommentieren. So bieten zum Beispiel MS SQL Server Datenbanksysteme eine
Möglichkeit namens „Extended Properties“ um Kommentare oder andere Eigenschaften für
Datenbankobjekte zu spezifizieren. Die Nutzung einer solchen Funktionalität würde aber
den Einsatzbereich der Anwendung extrem einschränken, da nur spezielle Datenbanksystem
unterstützt werden könnten. Eine letzte Möglichkeit ist der im SQL Standard definierten
Mechanismus zur Spezifikation von Kommentaren. Mit Hilfe des SQL Befehls „COMMENT ON“ können Kommentare für Datenbankobjekte spezifiziert werden.
Da dieser Mechanismus die Anforderungen am besten abdeckt, wurde entschieden diese
Möglichkeit in der Anwendung zu verwenden. Denn diese Möglichkeit bietet mehrere Vorteile. Erstens ermöglicht sie Kommentare direkt zusammen mit dem eigentlichen Datenbankobjekt in der Datenbank zu speichern. Zweitens ist es ein offizieller Standard, welche von
vielen Datenbanksystemen unterstützt wird. Drittens ist es über diesem Mechanismus in einer einfachen und standardisiertem Art und Weise möglich Kommentare zu spezifizieren
und wieder auszulesen.
5.3.2 Annotationen
Um Annotationen in benutzerdefinierten Kommentaren, wie im Kapitel 4.1.4 gefordert, zu
unterstützen, mussten mehrere Probleme gelöst werden. Einerseits mussten Komponenten
für die Verarbeitung und die Repräsentation von Annotationen entworfen werden und andererseits musste eine Syntax entworfen werden, mit der Annotationen in Kommentaren spezifiziert werden können. Inspiriert von Javadoc wurde entschieden für Annotationen so genannte Tags zu verwenden. Sowie die Syntax für Tags ähnlich wie diese von Javadoc zu definieren.
Aus der Analyse der Anforderungen wird klar, dass es verschiedene Tags für verschiedene
Zwecke geben muss. So ist erkennbar, dass es grundsätzlich zwei Gruppen von Tags gibt.
Einerseits Tags um spezielle Informationen im Kommentar auszuzeichnen beziehungsweise
anzufügen und andererseits Tags für die Formatierung des Kommentars. Tags zur Formatierung werden nur für eine bessere optische Darstellung der Kommentare verwendet und
beinhalten keine eigentlichen Informationen über das Datenbankobjekt. Was sie weniger interessant, aber trotzdem nützlich macht. In den nachfolgend Ausführungen werden diese
beiden Gruppen von Tags getrennt behandelt. Denn neben dem unterschiedlichen Zweck,
verwenden sie auch eine unterschiedliche Syntax und werden durch andere Schnittstellen
beschrieben.
36
5 Design
5.3.2.1 Tags mit Informationen
Gestützt auf die Anforderungen und weiteren Überlegungen wurden bei den Tags, die Informationen, enthalten verschiedene Typen von Tags identifiziert. Diese Typen werden in der
unten stehenden Liste aufgeführt und näher beschrieben. Um das Design von Tags allgemeingültig und flexibel zu halten, wurden nur Typen von Tags definiert und keine konkreten
Ausprägungen. Um konkrete Tags zu spezifizieren, wurde ein zusätzlicher Mechanismus
entwickelt, welcher in Kapitel 6.2.1 näher erläutert wird. Kurz gesagt ermöglicht dieser Mechanismus über eine Konfigurationsdatei konkrete Ausprägungen von Tags zu definieren.
Durch diese Konfigurationsdatei beziehungsweise der Definition von Tags, wird die Anwendungen dann in der Lage versetzt diese Tags im Kommentar zu erkennen und zu verarbeiten. Der grosse Vorteil dieser Lösung ist, dass es für den Benutzer sehr einfach ist neue
Tags hinzuzufügen oder bestehende zu ändern. Und sie erfüllt damit die Anforderung, dass
Benutzer eigene Tags definieren können.
Die allgemeine Syntax für die Spezifikation von Tags in Kommentaren ist sehr einfach gehalten und im Gegensatz zu Javadoc gibt es auch keine Einschränkungen an welchen Stellen
im Kommentar Tags erlaubt sind. Sie können grundsätzlich an jeder beliebigen Stelle stehen. Ein Tag wird immer mit der Zeichenfolge „{@“ eingeleitet, darauf folgt direkt anschliessend der Name des Tags und dann je nach Tag-Typ die Parameter, Referenzen oder weiterer Text. Abgeschlossen wird der Tag mit dem Zeichen „}“. Das bedeutet die Zeichen „{“
und „}“ haben eine spezielle Bedeutung, weil sie zur Einleitung und zum Abschluss eines
Tags dienen. Möchte man aber, dass diese Zeichen nicht als spezielle Tag-Begrenzungszeichen interpretiert werden, weil man sie anderweitig im Kommentar verwenden möchte,
kann diesen Zeichen ein „\“ (Backslash) vorangestellte werden um ihnen ihre spezielle Bedeutung zu nehmen und sie im Kommentar zu belassen.
Die verschiedenen Typen von Tags:
●
Einfacher-Tag: {@[Tagname]}
Einfache-Tags bestehen nur aus ihrem Name und enthalten keine weiteren Informationen. Solche Tags können eingesetzt werden, um ganz einfache Informationen über
das Datenbankobjekt im Kommentar zu hinterlegen. Ein häufiger Verwendungszweck dieser Tags dürfte dabei die Markierung von Datenbankobjekten sein, um sie
von der Anwendung speziell behandeln zu lassen. Zum Beispiel kann ein Tag, wie
{@omit} dem Kommentar eines Datenbankobjekts hinzugefügt werden, um der Anwendung zu signalisieren, dass dieses Datenbankobjekt in der Dokumentation ausgelassen werden soll.
37
5.3 Kommentare und Annotationen
●
Parameter-Tag: {@[Tagname] [Parameter]*}
Parameter-Tags bestehen neben ihrem Name noch aus beliebigen und beliebig vielen
Parametern. Mit diesen Tags können ausführlichere Informationen zu Datenbankobjekten hinzugefügt werden. Und so sind sie geeignet um Eigenschaften von Datenbankobjekten zu beschreiben, die unterschiedliche Werte annehmen können. Beispielsweise können über Tags wie {@since 1.0} oder {@author ''Sascha Nedkoff''}
zusätzlich Information zu Datenbankobjekten hinzugefügt werden, die ansonsten
nicht verfügbar wären, da sie im Datenbankschema nicht vorhanden sind.
●
Referenz-Tag: {@[Tagname] [Referenz] [Beschriftung]}
Referenz-Tags bestehen aus den drei Teilen, Namen, Referenz und Beschriftung.
Durch diese Tags wird es möglich, Referenzen auf andere Datenbankobjekte oder
andere Ressourcen zu setzen. Somit kann auf andere Objekte verwiesen werden, und
falls es das Ausgabeformate der Dokumentation erlaubt, kann dadurch eine Navigation zwischen Objekten realisiert werden. Mit der Beschriftung kann ein alternativer
Text angegeben werden, der in der Dokumentation anstelle der eigentlichen Referenz angezeigt wird. Es sind grundsätzlich verschiedene Arten von Referenzen möglich und die Form, wie eine Referenz angegeben werden muss, damit sie richtig interpretiert werden kann, hängt von der Art der Referenz ab. Es gibt drei Arten von
Referenzen:
○
Datenbankobjekt-Referenzen
Solche Referenzen werden ähnlich, wie im Abschnitt 5.1.3 erklärt, in der Form:
[Datenbankobjekt-Typ]:[Datenbankobjekt-Name] angegeben. So lange der Name
eindeutig ist, kann die Angabe des Typs weggelassen werden. Ebenfalls kann der
Namen des Datenbankobjekts in der einfachen oder der qualifizierten Form angegeben werden. Ein Beispiel wäre {@link TABLE:public.person ''Relation mit
Personendaten''}.
○
Bezeichner für Ressourcen
Werden auf englisch auch Uniform Resource Identifiers (URI) genannt. Durch
solche Referenzen ist es sehr allgemein möglich auf andere Ressourcen zu verweisen. Sie werden durch eines der Präfix „URI:“, „INTERN_URI:“ oder „EX-
38
5 Design
TERN_URI:“ eingeleitet und danach folgt eine gültige URI, wie es im Standard15
definiert wurde. Dieser erlaubt unter anderem lokale oder externe sowie relative
oder absolute Verweise und anderes mehr.
Der einzige Unterschied zwischen einer internen und einer extern URI ist, dass
in der Dokumentation unterschieden werden kann, wie eine solche Referenz zu
handhaben ist. Besonders in einer HTML-Dokumentation kann dadurch festgelegt werden, ob die Referenz in einem neuen Fenster geöffnet werden soll oder
nicht. Beispiele für solche Tags wären: {@link URI:file:///home/user/doc.html
Dokumentation} oder {@link EXTERN_URI:http://www.ifi.uzh.ch ''Universität
Zürich''} oder {@link URI:mailto:sascha@unizh.ch}.
○
Andere Referenzen
Solche Referenzen werden durch die Angabe von „OTHER:“ eingeleitet und
können verwendet werden, wenn keine Verarbeitung der Referenz gewünscht ist,
weil zum Beispiel andere Komponenten diese Aufgabe übernehmen sollten.
●
Text-Tag: {@[Tagname] [freier Text mit Tags]}
Text-Tags bestehen aus ihrem Namen gefolgt von beliebig viel Text, welcher seinerseits auch gewisse Tags enthalten kann. Solche Text-Tags sind geeignet, wenn einzelne Teile eines Kommentars nur für einzelne Benutzer oder Gruppen angezeigt
werden sollen. Zum Beispiel können so Kommentare spezifiziert werden, die nur für
Administratoren oder Entwickler interessant sind. Durch diese Tags wird es möglich
in der Dokumentation solche verschiedenen Teile abzugrenzen oder Dokumentationen nur für bestimmte Nutzer zu erstellen. Beispielsweise {@admin Dieser Kommentar ist nur für Datenbank-Administratoren... }
●
EER-Tag: {@[Tagname] [EER-Typ]}
EER-Tags bestehen aus ihrem Namen gefolgt von einem Namen für ein Element aus
dem erweiterten Gegenstands-Beziehungs-Modell. Durch diese Tags ist es möglich
für Datenbankobjekte das korrespondierende Element aus dem Gegenstands-Beziehungs-Modell zu definieren. Diese Information können beispielsweise zur Generierung von ER-Diagrammen herangezogen werden.
Nachdem die verschiedenen Typen von Tags identifiziert und definiert waren, musste für jeden Tag-Typ eine Schnittstelle entwickelt werden, welche diesen Tag-Typ repräsentiert sowie dessen Eigenschaften beschreibt. Das Ergebnis dieses Entwicklungsschritts ist in Abbil15 Uniform Resource Identifiers (URI): Generic Syntax [http://www.ietf.org/rfc/rfc2396.txt]
39
5.3 Kommentare und Annotationen
dung Abbildung 3 zu sehen.
Abbildung 3: Tag-Schnittstellen
Zunächst einmal gibt es Eigenschaften, die allen Tags gemeinsam sind. Dazu gehören der
Name des Tags, die Position des Tags innerhalb des Kommentars und das Datenbankobjekt
in dessen Kommentar der Tag vorkommt. Um diese allgemeinen Information zu beschreiben, wurde zuerst eine generische Schnittstelle namens TagInfo zur Repräsentation eines
Tags erstellt. Ausgehend von dieser Schnittstelle wurden dann für alle speziellen Tag-Typen
eigene Schnittstellen entwickelt, welche die TagInfo Schnittstelle erweitern. Wobei der
Parameter-Tag durch die Schnittstelle ParamTagInfo, der Referenz-Tag durch die
Schnittstelle RefTagInfo, der Text-Tag durch die Schnittstelle TextTagInfo und der
EER-Tag durch die Schnittstelle EERTagInfo repräsentiert werden. Da der Einfache-Tag
keine zusätzlichen Eigenschaften definiert, gibt es für ihn auch keine separate Schnittstelle,
sondern er wird durch die allgemeine TagInfo Schnittstelle repräsentiert.
5.3.2.2 Tags zur Formatierung
Wie zu Beginn des Abschnitts erwähnt, gibt es noch eine zweite Gruppe von Tags und zwar
40
5 Design
Tags zur Formatierung von Kommentaren. Diese Tags werden ausschliesslich eingesetzt,
um das Aussehen der Kommentare in der Dokumentation zu bestimmen. In der Abbildung 3
ist deshalb eine weiter Schnittstelle namens HTMLTagInfo vorhanden, welche diese Gruppe von Tags repräsentiert. Wie der Name schon andeutet, wurden diese Tags den HTMLTags nachempfunden und heissen deshalb ebenfalls so.
Die Syntax zur Spezifikation von HTML-Tag ist ebenfalls sehr einfach. HTML-Tags beginnen immer mit „<“ und enden mit „>“. Dabei gibt es zwei Arten. Öffnende und schliessende
HTML-Tags, wobei die schliessenden HTML-Tag an zweiter Stelle ein „/“ besitzen. Wie gesagt, sind diese HTML-Tags den richtigen HTML-Tags sehr ähnlich. Jedoch erlaubt die in
dieser Anwendung verwendete Sprachdefinition jeglichen Text zwischen „<“ und „>“, um
nicht eine komplette HTML-Validierung implementieren zu müssen. Trotzdem sollten nur
gültige HTML-Tags verwendet werden, wodurch es zumindest bei der Generierung einer
HTML-Dokumentation möglich ist diese Tags direkt zu übernehmen. Für andere Ausgabeformate, die keine oder nur eingeschränkte Formatierungen ermöglichen, können diese Tags
einfach weggelassen werden. Oder eine Ausgabekomponente kann diese Tags interpretieren,
um dann die Formatierung im eigenen Ausgabeformat entsprechend vornehmen. Deshalb ist
es auch für andere Ausgabeformate wichtig, dass die verwendeten HTML-Tags dem Standard entsprechend korrekt verwendet werden, um so eine Interpretation zu ermöglichen.
Die Zeichen „<“ und „>“ haben ebenfalls wie die Zeichen „{“ und „}“ eine spezielle Bedeutung innerhalb des Kommentars, weil sie zur Einleitung und zum Abschluss von HTMLTags dienen. Deshalb ist es auch bei diesen Zeichen möglich durch das Voranstellen eines
„\“ (Backslash) ihnen ihre spezielle Bedeutung zu nehmen, wodurch sie nicht mehr als
HTML-Tag interpretiert und im Kommentar belassen werden.
41
6 Implementierung
6 Implementierung
In diesem Kapitel wird die Implementierung der Anwendung beschrieben. Dabei wird genauer auf die Implementierungsdetails des Datenmodells, des Applikationsmanagers und
des Parsers für Kommentare eingegangen. Anschliessend wird einzeln für alle Plug-ins, deren Funktionalität sowie die grundlegenden Implementierungsentscheidungen beschrieben.
6.1 Datenmodell
Dieses implementiert das Datenmodell, genauer gesagt implementiert es die im Datenmodell definierten Schnittstellen von Datenbankobjekten und Tags. Für die generischen
Schnittstellen DBObjectInfo, OwnedDBObjectInfo und RelationInfo wurde jeweils eine abstrakte Klasse implementiert. Die restlichen Schnittstellen, welche konkrete
Datenbankobjekttypen repräsentieren, wurden mit konkreten Klassen implementiert. Weiter
wurde durch eine Klasse die RootInfo Schnittstelle realisiert.
Implementierung dieser Klassen ist, bis auf die link() Methode, relativ einfach, da es sich
um simple Java-Klassen mit Methoden zum setzten und holen von Eigenschaften handelt.
Nur die Implementierung der link() Methode benötigte mehr Zeit, weil für jeden Datenbankobjekttyp unterschiedlich Objekte gelinkt werden müssten und zusätzlich müsste eine
Möglichkeit geschaffen werden um im Fall von Fehlern beim Verlinken detaillierte Fehlermeldungen ausgeben zu können.
6.2 Kommentare und Tags
Um benutzerdefinierte Kommentare und Tags, wie in dem Kapitel 5.3 beschrieben, zu unterstützen, wurden zuerst konkreten Klassen für die Implementierung der verschiedenen
Tag-Schnittstellen erstellt. So existieren eine Klasse TagImpl für die Implementierung der
TagInfo Schnittstelle. Und je eine Klasse, die von TagImpl erbt, für die Implementierung der Schnittstellen ParamTagInfo, RefTagInfo, TextTagInfo, EERTagInfo
und HTMLTagInfo.
42
6 Implementierung
Abbildung 4: Tag-Schnittstellen und Tag-Klassen
6.2.1 Tag-Definitionen
Wie erwähnt wurden beim Design von Tags nur Typen von Tags definiert und keine konkreten Ausprägungen. Um nun die Definition von konkreten Tags zu ermöglichen, wurde einerseits ein spezielle XML-Datei mit zugehörigem XML-Schema erstellt und andererseits ein
spezielle Klasse implementiert, um diese XML-Datei mit den Tag-Definitionen einlesen zu
können. Sind einmal die Tag-Definitionen bekannt, können diese auch an den im nächsten
Unterkapitel beschriebenen Parser übergeben werden, um ihm zu ermögliche diese Tags in
Kommentaren erkennen und verarbeiten zu können.
Tags werden wie angesprochen in einer XML-Datei definiert. Die Integrität der XML-Datei
wird mittels eines XML-Schemas beim Einlesen sichergestellt, wodurch weniger Aufwand
betrieben werden muss um die Tag-Definitionen auf ihre Richtigkeit zu überprüfen. Die
Struktur der XML-Datei ist einfach und so können Benutzer ohne Schwierigkeiten neue
Tags definierten.
43
6.2 Kommentare und Tags
<tagdefinitions>
<tag>
<name>
<type>
<numberOfParameters>
<isInline>
<nonrecurring>
</tag>
</tagdefinitions>
</name>
</type>
</numberOfParameters>
</isInline>
</nonrecurring>
Innerhalb des <tagdefinitions>-Block können beliebig viele <tag>-Blöcke angegeben werden. Jeder <tag>-Block entspricht dabei einer Tag-Definition. Eine Tag-Definition besteht
dann aus fünf Elementen, welche die Eigenschaften eines Tags definieren:
●
<name>:
Spezifiziert den eindeutigen Name des Tags.
●
<type>
Bestimmt den Tag-Typ, wie sie im Design beschrieben sind. Mögliche Werte sind
„SimpleTag“, „ParameterTag“, „ReferenceTag“, „TextTag“ oder „EERTag“.
●
<numberOfParamerters>
Für Parameter-Tags, wird mit diesem Element die Anzahl der Parameter festgelegt.
●
<isInline>
Boolesche Option, die spezifiziert, ob die Position des Tag innerhalb des Kommentars von Bedeutung ist oder ignoriert werden kann.
●
<nonrecurring>
Boolesche Option, welche bestimmt, ob ein Tag nur einmal oder mehrmals innerhalb
desselben Kommentars vorkommen darf.
44
6 Implementierung
Von der Anwendung sind schon viele Tags vordefiniert, welche sich allgemein als nützlich
erweisen können. Diese vordefinierten Tags sind in der Tabelle 2 aufgeführt.
Name
Typ
Position von
Bedeutung
Einmaliges
Auftreten
Anzahl
Parameter
omit
Einfacher-Tag
Nein
Ja
omitInOverview
Einfacher-Tag
Nein
Ja
author
Parameter-Tag
Nein
Ja
1
since
Parameter-Tag
Nein
Ja
1
see
Referenz-Tag
Nein
Nein
link
Referenz-Tag
Ja
Nein
admin
Text-Tag
Nein
Ja
designer
Text-Tag
Nein
Ja
enduser
Text-Tag
Nein
Ja
programmer
Text-Tag
Nein
Ja
EER
ERR-Tag
Nein
Ja
Tabelle 2: Vordefinierte Tags
6.2.2 Parser
Für die Unterstützung von benutzerdefinierten Kommentaren mit benutzerdefinierten Tags
wurde ein Parser entwickelt, mit dem Kommentare und die darin enthaltenen Tags verarbeitet werden können. Um die durch den Parser gewonnenen Informationen über Kommentare
und ihre Tags festzuhalten wurde eine eigene Klasse namens Comment erstellt. Diese bietet
zahlreiche Methoden, um komfortabel auf den geparsten Kommentar und die erstellten TagObjekte zugreifen zu können. Für alle im Kommentar enthaltenen Tags werden vom Parser
die korrespondierenden Tag-Objekte erzeugt und über die Comment Klasse zur Verfügung
gestellt.
Damit der Parser, wie gefordert mit benutzerdefinierten Tags umgehen kann, muss der Parser flexibel konfiguriert werden können. Dazu wird die angesprochen XML-Datei mit den
Definitionen von Tags verwendet. Anhand dieser Tag-Definitionen weiss der Parser für alle
Tags, welches Tag-Objekte erstellt und wie sie initialisiert werden müssen. Ebenfalls ist er
in der Lage falsch formatierte Tags zu erkennen und detaillierte Fehlermeldungen zu generieren. Unter anderem überprüft der Parser, ob Parameter-Tags über die richtige Anzahl Parameter verfügen oder ob Tags die als einmalig spezifiziert wurden, wirklich nur einmal im
Kommentar vorkommen. Falls beim parsen falsch formatierte Tags oder andere Fehler auftreten, werden diese mit Hilfe einer spezielle Ausnahmeklasse namens CommentParser45
6.2 Kommentare und Tags
Exception gemeldet. Diese Fehlermeldungen werden dann einerseits über das Log4J Framework ausgegeben und andererseits im RootInfo-Objekt gespeichert. Durch die Speicherung im RootInfo-Objekt kann jederzeit auf die aufgetretenen Fehler zugegriffen
werden und sie eventuell auch in der Ausgabe mit einzubeziehen.
6.3 Applikationsmanager
Der Applikationsmanager ist jener Teil der Anwendung, welcher die grundlegenden Konfigurations- und Verwaltungsaufgaben bei der Ausführung der Anwendung übernimmt.
Die wichtigsten Klassen dieser Komponente sind die Klassen ApplicationManager,
ConfigurationManager und PluginManager. Der ApplicationManager ist
für den Start der Anwendung und für die Steuerung des weiteren Ablaufs verantwortlich.
Um seine Aufgabe erfüllen zu können, verwendet er den ConfigurationManager.
Dieser versucht aus den Angaben in einer XML-Konfigurationsdatei und den Kommandozeilen-Argumenten eine gültige Konfiguration für die Anwendung zu erstellen. Falls dies
nicht möglich ist, weil die vom Benutzer gemachten Angaben zur Konfiguration inkorrekt
sind, wird die Ausführung abgebrochen. Um den Implementierungsaufwand für die nötigen
Überprüfungen der Konfigurationsangaben möglichst klein zu halten, wurde entschieden für
diesen Zweck ein XML-Schema für die Validierung der XML-Konfigurationsdatei zu erstellen und zu verwenden. Im nächsten Abschnitt wird die Struktur der XML-Konfigurationsdatei und die durch das XML-Schema definierten Einschränkungen näher beschrieben.
Falls die Konfigurationen der Anwendung erfolgreich war, werden die Konfigurationsangaben an den PluginManager weitergegeben. Dieser ist für die Verwaltung und Ausführung aller konfigurierten Plug-ins zuständig. Dazu muss er sie zuerst initialisieren, dann die
Plug-in spezifischen Optionen übergeben und dann die Plug-ins in der richtigen Reihenfolge
ausführen. Ebenfalls ist er während dieser Vorgänge dafür verantwortlich im Fall von Fehlern, die von den Plug-ins ausgelösten Fehlermeldung vom Typ PluginException aufzufangen und je nach dem wo und wann eine Fehlermeldung auftritt, angemessen darauf zu
reagieren. Sei es indem die Ausführung des Plug-ins oder sogar die ganze Applikation abgebrochen wird.
46
6 Implementierung
6.3.1 XML-Konfigurationsdatei
Die XML-Konfigurationsdatei, welche zur Konfiguration der Anwendung verwendet werden kann, hat folgenden Aufbau. Innerhalb des <configuration>-Block gibt es zuerst einen
<application>-Block. In diesem werden die generellen Optionen, welche für die gesamte
Anwendung gelten, spezifiziert. Danach folgt ein <plugins>-Block. In diesem werden die
einzelnen Plug-in mit ihren Optionen spezifiziert.
47
6.3 Applikationsmanager
<configuration
instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-
xsi:noNamespaceSchemaLocation="configuration.xsd">
<application>
<logger>logging.properties</logger>
</application>
<plugins>
<MODEL id="std">
<name>Standard model</name>
<class>org.sesam.dbdoc.model.impl.StandardModelCreator</class>
<load_sequence>1</load_sequence>
<custom key="tagdef">tag_definitions.xml</custom>
<custom key="abortOnLinkingErrors">false</custom>
</MODEL>
<INPUT id="std">
<name>PostgreSQL Catalog Reader</name>
<class>org.sesam.dbdoc.input.PostgresCatalogReader</class>
<load_sequence>2</load_sequence>
<custom key="driver">org.postgresql.Driver</custom>
<custom key="url">jdbc:postgresql:sesam_test</custom>
<custom key="username">admin</custom>
<custom key="password">adminpassword</custom>
<custom key="sqlqueries">sqlqueries_for_postgres.xml</custom>
<custom key="readtypes">ALL</custom>
</INPUT>
<TRANSFORM id="sql">
<name>SQL Reconstructor Transformer</name>
<class>org.sesam.dbdoc.transform.SQLReconstructor</class>
<load_sequence>3</load_sequence>
</TRANSFORM>
<OUTPUT id="html">
<name>HTML Generator</name>
<class>org.sesam.dbdoc.output.html.HTMLDocgen</class>
<load_sequence>4</load_sequence>
<custom
key="outputFolderLocation">gen_output/html</custom>
<custom key="outputFolderName">DBDoc_for_{DBNAME}</custom>
<custom key="overwrite">true</custom>
<custom key="includeErrorReport">true</custom>
<custom key="showOmitObjectsInHTMLTables">true</custom>
<custom key="useImagesForLinks">true</custom>
<custom key="useframes">true</custom>
</OUTPUT>
</plugins>
</configuration>
48
6 Implementierung
6.3.2 Kommandozeilen Argumente
Neben der Möglichkeit die Anwendung mit Hilfe der XML-Konfigurationsdatei zu konfigurieren gibt es zusätzlich die Möglichkeit die Anwendung über Kommandozeilen-Argumente
zu konfigurieren. Auf der Kommandozeile bestehen genau dieselben Möglichkeiten zur
Konfiguration, wie mit einer XML-Datei. Nur das Format für die Spezifikation von Optionen ist unterschiedlich.
Zusätzlich ist es auch möglich diese beiden Varianten flexibel miteinander zu kombinieren.
So können einzelne Optionen in der Konfigurationsdatei und andere auf der Kommandozeile spezifiziert werden. Wichtig zu beachten ist, dass Optionen, die auf der Kommandozeile
spezifiziert werden, eine höher Priorität als Optionen in der Konfigurationsdatei haben und
diese deshalb überschreiben. So ist es denkbar eine Grundkonfiguration der Anwendung in
der Konfigurationsdatei zu spezifizieren und dann auf der Kommandozeile, an die Situation
angepasst, noch gewisse Optionen zu überschreiben.
6.3.3 Protokollierung
In der gesamten Applikation wird die Protokollierung mit Hilfe des Log4J Logging Frameworks implementiert. Durch dieses Framework ist es möglich Status- und Fehlermeldungen
komfortabel zu formatieren und auszugeben. Das Log4J Framework wurde gegenüber anderen Lösungen bevorzugt, weil es einfach in der Anwendung ist und vielseitig konfiguriert
werden kann. Durch die Konfigurationsmöglichkeiten kann die Protokollierung an verschiedene Einsatzszenarien angepasst werden. So können bei einer direkten Ausführung durch
den Benutzer die Meldungen auf der Konsole ausgegeben werden und bei einer automatischen Ausführung im Batch-Verfahren können die Meldungen in einer Datei gespeichert
werden.
6.4 Plug-ins
Bevor konkrete Plug-ins implementiert wurden, wurden zuerst abstrakte Klassen erstellt, um
die allen Plug-ins und die allen Typen von Plug-ins gemeinsame Funktionalität zu realisieren. Diese Struktur ist in der Abbildung 5 zu sehen.
49
6.4 Plug-ins
Abbildung 5: Plug-in Implementierungen
6.4.1 Standard-Model-Plug-in
Als Model-Plug-in wurde nur ein Plug-in entwickelt und zwar das Standard-Model-Plug-in.
Weil es zwar denkbar aber nicht nötig ist verschiedene Implementierungen des Datenmodells zu haben. Deshalb verwendet das Standard-Model-Plug-in die Standardimplementierung des Datenmodells.
Die eigentliche Verantwortlichkeit des Model-Plug-ins besteht darin ein RootInfo-Objekte bereitzustellen sowie in einem späteren Zeitpunkt alle im RootInfo-Objekt vorhandenen Datenbankobjekt zu verlinken. Um diese Aufgaben erfüllen zu können, verwendet es
aber einfach die in der Implementierung des Datenmodells vorhandenen Funktionalitäten.
Des weiteren ist das Model-Plug-in für die Konfiguration des Parsers verantwortlich. Um
diesen konfigurieren zu können, benötigt das Model-Plug-in Zugriff auf die XML-Datei, in
welcher die erlaubten Tags definiert sind.
50
6 Implementierung
Optionen des Standard-Model-Plug-ins:
name
Name des Plug-in.
tagdef
XML-Datei mit den Definitionen von Tags.
abortOnLinkingErrors Boolesche Option mit der bestimmt werden kann, ob im
Fall von Verlinkungs-Fehlern die Ausführung abgebrochen
werden soll.
Tabelle 3: Optionen des Standard-Model-Plug-ins
6.4.2 PostgreSQL-Input-Plug-in
Als Input-Plug-in wurde das PostgreSQL-Input-Plug-in entwickelt, welches die Anbindung
von PostgreSQL Datenbanksystemen ermöglicht. Dazu wurden zwei Klassen implementiert.
Zum einen die Klasse PostgresCatalogReader, welche durch Vererbung von AbstractDBReader und eigenen Erweiterungen die InputPlugin Schnittstelle implementiert. Zu den Aufgaben von PostgresCatalogReader zählt erstens, das Laden des
spezifizierten JDBC Datenbanktreibers. Zweitens der Auf- und Abbau einer Verbindung zu
der spezifizierten Datenbank. Und drittens das Auslesen aller benötigten Informationen aus
der Datenbank. Für diese dritte Aufgabe wurde eine eigene Klasse namens ReaderHelper erstellt, die den PostgresCatalogReader hierbei unterstützt. Sie übernimmt die
eigentliche Verarbeitung der ausgelesenen Informationen über Datenbankobjekte und erzeugt über die DBObjectInfoFactory die korrespondierenden DBObjectInfo-Objekte.
Um Informationen über Datenbankobjekte aus einer PostgreSQL Datenbank auszulesen,
gibt es neben den vom JBDC Treiber angebotenen Methoden, welche als ungenügend angesehen werden, noch zwei weitere Möglichkeiten. Erstens die Verwendung des im SQL Standard definierten und von PostgreSQL implementierten „Information-Schema“ oder zweitens
die Verwendung des PostgreSQL eigenen Datenkatalogs namens „pg_catalog“. Weil im
PostgreSQL eigenen Datenkatalog mehr Informationen vorhanden sind oder anders gesagt,
weil im „Information-Schema“ keine Informationen über PostgreSQL spezifische Features
vorhanden sind und ohnehin für einige Informationen auf das PostgreSQL eigenen Datenkatalog zugegriffen werden muss, wurde entschieden zum Auslesen der Informationen ausschliesslich den PostgreSQL eigenen Datenkatalog zu verwenden. Um so eine bessere und detailliertere Dokumentation erstellen zu können. Da dieses Plug-in ja gerade für PostgreSQL
Datenbanksystem ausgelegt ist, bedeutet dies auch keine wirkliche Einschränkung.
Das einzige Problem bei der Verwendung des PostgreSQL eigenen Datenkatalogs ist, dass
51
6.4 Plug-ins
dieser im Gegensatz zum „Information-Schema“ Veränderungen unterworfen sein könnte.
Wie es in Kapitel 32 von [PostgreSQL07] beschrieben wird. Dies bedeutet, dass sich der
Datenkatalog in zukünftigen Versionen des PostgreSQL Datenbanksystems verändern könnte, wenn auch nur in Details. Um aber gegenüber solchen Änderungen im PostgreSQL Datenkatalog gewappnet zu sein, wurden die SQL-Statements zur Abfrage der einzelnen Informationen in eine separate XML-Property-Datei ausgelagert. So müssten bei allfälligen Änderungen nur diese SQL-Statements angepasst werden, was bedeutend einfacher ist und
auch keine neue Kompilierung der Anwendung erfordert.
Obwohl das PostgreSQL-Input-Plug-in speziell für PostgreSQL Datenbanken gedacht ist, ist
es durch seine allgemein gehaltene Implementierung theoretisch sogar denkbar es ohne viel
Aufwand auch für andere Datenbanksysteme zu verwenden. Dazu müssten eigentlich nur
die SQL-Statements in der XML-Property-Datei angepasst werden. Denn die XML-Property-Datei in Kombination mit dem ReaderHelper bietet theoretisch die Möglichkeit auch
andere Datenbanksysteme zu unterstützen. Ebenfalls wären kleine Änderungen im PostgresCatalogReader nötig, aber der grösste Teil der besprochenen Funktionalität des
PostgresCatalogReader könnte wiederverwendet werden.
Optionen des PostgreSQL-Input-Plug-ins:
name
Name des Plug-in.
driver
JDBC Treiber für das Datenbanksystem.
url
JDBC URL der Datenbank.
username
Name des Datenbankbenutzers.
password
Passwort des Datenbankbenutzers.
commentTable
Relation mit zusätzlichen benutzerdefinierten Kommentaren.
sqlqueries
XML-Property-Datei mit den SQL Anfragen.
readtypes
Komma separierte Liste mit Namen von Datenbankobjekttypen
über welche Information eingelesen werden sollen. Oder „ALL“
für alle Datenbankobjekttypen.
Tabelle 4: Optionen des PostgreSQL-Input-Plug-ins
Über die Option -readtypes kann der Benutzer angeben, über welche Datenbankobjekttypen Information eingelesen werden sollen. Diese erlaubt schon früh im Dokumentations52
6 Implementierung
prozess zu definieren, welche Information benötigt werden. Durch Ausschluss von nicht benötigten Objekten zu diesem Zeitpunkt kann Rechenzeit eingespart werden, da es kein Sinn
macht Daten von solchen Objekten einzulesen, zu verarbeiten und wieder auszugeben. Da
der Ausschluss von allen Datenbankobjekten eines Typs häufig zu rigoros ist, hat der Benutzer auch die Möglichkeit die SQL Anfragen in der XML-Property-Datei zu ändern. Diese
Datei wird dem Plug-in über die Option -sqlqueries übergeben. In dieser Datei sind
sehr genaue und flexible Einstellung möglich, welche Objekte der verschiedenen Typen eingelesen werden sollen. Natürlich ist es häufig einfacher spezielle Objekte durch Transformator-Plug-ins zu behandeln und auszufiltern, doch falls bestimmte Objekte nie gebraucht werden, kann es aus Performance Gründen sinnvoll sein dies schon beim Einlesen zu machen.
So ist diese Möglichkeit vor allem für den Ausschluss von Systemobjekten geeignet. Beispielsweise werden die im PostgreSQL Datenbanksystem standardmässig vorhandenen Relationen und Sichten, welche den Datenkatalog und das „Information-Schema“ ausmachen,
nicht eingelesen, da sie für die Dokumentation der eigentlichen Datenbank unwichtig sind.
Hingegen werden die standardmässig vorhandenen Funktionen, Datentypen, Domänen und
so weiter eingelesen, da sie wichtig für die Dokumentation sein können. Durch die Auslagerung der SQL Anfragen in eine XML-Property-Datei ist es aber jederzeit sehr einfach möglich dieses Standardverhalten zu ändern.
Mit der Option -commentTable kann dem Plug-in der Name einer Relation übergeben
werden, die zusätzliche benutzerdefinierte Kommentare enthält. Die Relation mit benutzerdefinierten Kommentaren muss drei Spalten besitzen. Die Spalte „dbobject_type“ muss den
Typ des Datenbankobjekts , die Spalte „dbobject_name“ den Namen des Datenbankobjekts
und die Spalte „comment“ den Kommentare für das zu kommentierende Datenbankobjekt
enthalten. Durch diese Option können auch Datenbankobjekttypen, für welche es nicht möglich ist einen Kommentar mit SQL „COMMENT ON“ zu spezifizieren, mit Kommentaren
versehen und dadurch besser dokumentiert werden. Zum Beispiel ist es in älteren Versionen
von PostgreSQL Datenbanksystemen noch nicht möglich für alle Datenbankobjekttypen mit
SQL „COMMENT ON“ einen Kommentar zu spezifizieren. In der Version 8.1 von PostgreSQL wurde die Kommentierung von „Role“ und „Tablespace“ noch nicht unterstützt.
6.4.3 Output-Plug-ins
6.4.3.1 HTML-Output-Plug-in
Als wichtigstes Output-Plug-in wurde ein so genanntes HTML-Output-Plug-in entwickelt,
welches in der Lage ist eine HTML-Dokumentation der Datenbank zu erstellen.
Dazu wurde als eigentliche Plug-in Klasse, die Klasse HTMLDocgen erstellt, welche durch
53
6.4 Plug-ins
Vererbung von AbstractDocgen und eigenen Erweiterungen die OutputPlugin
Schnittstelle implementiert. Weiter wurde, wie in Abbildung 6 zu sehen ist, ein abstrakte
Klasse HTMLWriter implementiert, die viele Methoden besitzt um allgemeine HTMLCode Fragmente mit Hilfe eines Java PrintWriter in eine Datei zu schreiben. Von dieser
Klasse erbt eine weiter abstrakte Klasse DBObjectWriter. Diese erweitert den Funktionsumfang um Methoden zum Schreiben von HTML-Code für Datenbankobjekt spezifischen Informationen, wie Kommentare, Tags oder andere Eigenschaften. Von diesen zwei
abstrakten Klassen erben dann mehrere konkrete Klassen. Jede dieser konkreten Klassen ist
für die Generierung eines ganz bestimmten Teils der HTML-Dokumentation zuständig. Bei
dieser Vererbungshierarchie handelt es sich um eine reine Implementierungsvererbung.
Abbildung 6: Implementierungsvererbung im
HTML-Output-Plug-in
Der IndexWriter erstellte die index.html Datei, die als Einstiegspunkt in die Dokumentation dient. Diese Datei enthält den HTML-Code für die Darstellung von zwei Rahmen im
Browser. Ein Rahmen für das Menü und ein Rahmen für die Detailseiten über Datenbankobjekte. Das eigentlich Menü wird dann von den Klassen MenuWriter und MenuCodeWriter erstellt. Zusätzlich generiert der MainWriter die Haupt- beziehungsweise die
Startseite der Dokumentation. Alle Detailseiten mit den Informationen über Datenbankobjekt werden von der Klasse AllDBObjectWriter erstellt und alle Übersichtsseiten die
bei der Navigation im Menü angezeigt werden, werden durch die Klasse OverviewWri54
6 Implementierung
ter generiert. Dann gibt es noch den ErrorReportWriter, welcher alle aufgetretenen
Fehler beim Parsen von Kommentaren und beim Verlinken von Datenbankobjekten in einer
separaten HTML-Seite dokumentiert.
Wie schon kurz erwähnt und in der Abbildung 7 zu erkennen, besteht die Ansicht der generierten HTML-Dokumentation grundsätzlich aus zwei Teilen.
Abbildung 7: Generierte HTML-Dokumentation
Auf der linken Seite wird ein interaktives Menü zur Navigation bereitgestellt und auf der
rechten Seite werden die Informationen über Datenbankobjekte angezeigt. Da es relativ aufwändig ist ein professionell aussehendes und gut konfigurierbares Menü mit JavaScript zu
implementieren und es schon viele gute und frei verfügbare Lösungen für dieses Problem
gibt, wurde für diesen Teil auf eine Lösung von [TreeMenu] zurückgegriffen. Unter vielen
zur Verfügung stehender Menüs, wurde dieses ausgewählt, weil es sehr viele Möglichkeiten
für Anpassungen und zur Konfiguration bietet. Beispielsweise kann für jeden Menü-Eintrag
einzeln ein Symbol für diesen definiert werden oder auch für eine Gruppe von Einträgen.
55
6.4 Plug-ins
Ebenso wichtig ist, dass es auch bei einer sehr grossen Anzahl von Menü-Einträgen noch
vernünftig funktioniert und genügend schnell reagiert. Weiter ist das Menü in der Lage sich
die auf- und zusammengeklappten Menü-Einträge zu merken. Eine andere praktische Fähigkeit des Menüs ist die Möglichkeit der Verfolgung der aktuellen Position im Menü. Wenn
man über Links in der Dokumentation und nicht im Menü zu anderen Detailseiten von Datenbankobjekten navigiert, wird im Menü automatisch der aktuelle Menü-Eintrag geöffnet
und markiert, so dass man immer direkt sieht, wo man sich in der Dokumentation befindet.
Auf der rechten Seite werden die Informationen über die Datenbankobjekte angezeigt. Für
jedes zu dokumentierende Datenbankobjekt wird eine eigene HTML-Seite generiert. Diese
Detailseiten über Datenbankobjekte haben alle einen ähnlichen Aufbau. Sie beginnen mit
dem Typ und Namen des Datenbankobjekts als Titel, gefolgt vom benutzerdefinierten Kommentar und den Tags. Danach kommt das rekonstruierte SQL-Statement. Da dieses unter
Umständen relative lang werden kann, kann es für eine bessere Übersicht auch ausgeblendet
werden. Daran anschliessend folgen in tabellarischer Form alle Eigenschaften des Objekts.
Der restliche Teil der Detailseiten ist unterschiedlich und hängt vom Typ des Datenbankobjekts ab. Bei Relationen beispielsweise folgt nach den Eigenschaften der Relation eine Tabelle mit den in der Relation vorhandenen Spalten und deren wichtigsten Eigenschaften. Die
in dieser Tabelle aufgeführten Einschränkungen von Spalten, werden um die Darstellung
kompakt zu halten, nur als Symbole dargestellt. Jedoch besitzen alle einen so genannten
„Mouse over“-Tooltip, welcher genauere Information über die Einschränkung enthält. Abschliessend folgen falls vorhanden noch Tabellen mit den auf der Relation definierten Einschränkungen, Triggern und Indexen sowie Tabellen mit den vererbten Relationen.
Zur attraktiven Gestaltung der HTML-Dokumentation und zur optischen Orientierung wurde für jeden Typ von Datenbankobjekt eine eigene Farbe und zwei Symbole definiert. Für
jeden Datenbankobjekttyp gibt es ein Symbol zur Repräsentation eines Objekts und ein
zweites Symbol zur Repräsentation mehrerer Objekte dieses Typs. Die momentan verwendeten Symbole stammen ursprünglich aus der Applikation pgAdmin III16 einem Administration und Management Tool für PostgreSQL Datenbanksysteme. Die verwendeten Symbole
können aber jederzeit leicht ausgetauscht werden, da sie zusammen mit den Farben in einer
eigenen XML-Property-Datei spezifiziert wurden.
Da das HTML-Output-Plug-in einerseits sehr umfangreich ist und andererseits eine komfortable Konfiguration möglich sein soll, bietet es mehrere Optionen, die nachstehend erläutert
werden.
Optionen des HTML-Output-Plug-ins:
16 http://www.pgadmin.org
56
6 Implementierung
outputFolderLocation
Pfad eines Ordners, in welchem der Ordner mit der generierten HTML-Dokumentation gespeichert werden soll.
outputFolderName
Name für den Ordner in welchem die Dokumentation gespeichert werden soll. Im Namen können drei verschiedene
Variablen verwendet werden, welche später durch ihren aktuellen Wert ersetzt werden. {DBNAME} wird ersetzt mit
dem Namen der dokumentierten Datenbank. {DATE} wird
durch das aktuelle Datum und {TIME} durch die aktuelle
Uhrzeit ersetzt.
overwrite
Boolesche Option, welche bestimmt, ob eine unter demselben Pfad und Namen allenfalls schon vorhandene Dokumentation überschrieben werden darf.
includeErrorReport
Boolesche Option, die festlegt ob der Dokumentation ein
Fehlerbericht hinzugefügt werden soll.
useImagesForLinks
Boolesche Option mit der bestimmt werden kann, ob bei
Links neben dem eigentlichen Link-Text auch ein kleines
Symbol verwendet werden soll.
additionalTextforMain Variabler Text, welcher auf der Titelseite der DokumentatiPage
on erscheinen soll.
additionalTextforMain Der Name einer Datei dessen Inhalt auf der Titelseite der
PageFromFile
Dokumentation erscheinen soll.
additionalMenuEntries Fügt eigene Einträge ins Hauptmenü der Dokumentation
ein, um zum Beispiel wichtige andere Dokumente zu verlinken. Hierfür wird eine spezielle Syntax verwendet und zwar
muss
für
jeden
Eintrag
angegeben
werden:
MENUENTRY([Name], [Link], [Bild]);
folderToCopyToOutput
Beliebiger Ordner, welcher samt Inhalt in den generierten
Ausgabeordner kopiert werden soll.
showOmitObjectsInHTML Boolesche Option, die festgelegt, ob Datenbankobjekte, die
Tables
einen @omit-Tag besitzen in der Dokumentation ganz ausgelassen werden oder noch in den Übersichtstabellen auftauchen sollen.
57
6.4 Plug-ins
Tabelle 5: Optionen des HTML-Output-Plug-ins
6.4.3.2 Konsolen-Output-Plug-in
Das Konsolen-Output-Plug-in ist ein extrem einfaches Plug-in. Seine einzige Fähigkeit ist
es die Namen, Kommentare und Tags von Datenbankobjekten auf der Konsole auszugeben.
Wobei über eine boolesche Option namens -verbose eingestellt werden kann, ob nur die
Namen oder auch die Kommentare und Tags ausgegeben werden sollen.
Dieses Output-Plug-in ist viel zu primitiv, als das es für die Erstellung einer Datenbankdokumentation verwendet werden könnte, vielmehr ist es nur zum Testen und Debuggen der
Anwendung gedacht.
6.4.4 Transformator-Plug-ins
Bei den Transformator-Plug-ins wurden insgesamt vier verschiedene Transformatoren implementiert. Allen ist gemeinsam, dass sie die vorhandenen Informationen über Datenbankobjekte im Datenmodell analysieren und darauf aufbauend Informationen ändern oder hinzufügen. Mit den verschiedenen implementieren Transformatoren wurde versucht die Mächtigkeit und die Möglichkeiten des Transformator Konzepts zu demonstrieren. Einer dieser
Transformatoren wurde sehr allgemein gehalten und kann deshalb für unterschiedlichste
Zwecke eingesetzt werden. Die anderen drei Transformatoren wurden dagegen für spezielle
Einsatzzwecke entwickelt und erlauben verschiedene Teilaspekte der Dokumentation zu
verbessern.
In den nachfolgenden Unterkapiteln werden die einzelnen Transformator-Plug-ins detaillierter beschrieben. Grundsätzlich erben alle entwickelten Transformator-Plug-ins von der abstrakten Klasse AbstractTransformer, welche die TransformPlugin Schnittstelle
implementiert.
6.4.4.1 Kommentar-Transformator
Das Kommentare-Transformator-Plug-in ist ein sehr allgemein gehaltenes Plug-in, das
durch die Klasse CommentTransformer implementiert wird. Wie der Name schon sagt,
besteht die Hauptaufgabe dieses Plug-ins darin, die benutzerdefinierten Kommentare der
vorhandenen Datenbankobjekte zu verändern. Vorhandene Kommentare können gelöscht,
neue Kommentare spezifiziert oder Kommentare können an schon vorhandenen angehängt
werden. Da Kommentare auch Tags enthalten können, ist es natürlich auch möglich Tags
einzufügen, zu löschen oder anzuhängen. Zusätzlich können mit diesem Plug-in auch noch
allgemeine Eigenschaften zu Datenbankobjekten hinzugefügt werden.
58
6 Implementierung
Damit dieses Plug-in allgemein einsetzbar ist und an viele Situationen angepasst werden
kann, musste eine Möglichkeit geschaffen werden um es flexibel konfigurieren zu können.
Wie andere Plug-ins auch, kann es über angebotene Optionen konfiguriert werden. Da aber
einfache Optionen allein nicht flexibel genug sind, wurde zusätzlich eine eigene kleine
Sprache zur Konfiguration des Plug-ins entwickelt. Das Plug-in verfügt über genau eine eigene Option namens -statement, welcher in dieser Sprache formulierte Ausdrücke
übergeben werden können.
Sprachdefinition für Kommentar-Transformations-Statements
Die Sprache für Kommentar-Transformations-Statements wurde an die Sprache SQL angelehnt und ist deshalb ebenfalls eine deklarative Sprache. Es wurde eine zu SQL ähnliche,
aber einfachere Syntax definiert und es wurden einige wenige Schlüsselwörter aus SQL
übernommen.
Syntax für Kommentar-Transformations-Statements:
[ADD|REPLACE|DELETE] COMMENT {Kommentar}
[FROM|INTO] {Datenbankobjekttypen}
[WHERE {Bedingungen}];;;
{Kommentar}: Beliebiger Text mit Tags, der als Kommentar für Datenbankobjekte verwendet werden soll. Falls DELETE COMMENT spezifiziert wurde, hat der Kommentar
keine Bedeutung. Innerhalb von Kommentaren können zusätzlich noch spezielle Schlüsselwörter verwendet werden, diese werden dann während der Verarbeitung des Statements
durch ihre tatsächlichen Werte ersetzt. Diese Wörter sind „[DBOBJECT_NAME]“, „[DBOBJECT_QNAME]“ und „[DBOBJECT_TYPE]“. Zusätzlich existiert noch eine Funktion
um Text-Ersetzungen während der Verarbeitung des Statements vorzunehmen. Diese Funktion hat die Form: REPLACE_FUNC( [P1], [P2],[P3])
Wobei [P1] der Text ist indem die Ersetzung vorgenommen werden soll. [P2] bezeichnet
den zu ersetzenden Text und [P3] bezeichnet den Text, der anstelle von [P2] eingefügt
werden soll.
{Datenbankobjekttypen}: Komma separierte Liste von Namen von Datenbankobjekttypen, bei denen der Kommentare verändert werden soll. Als Namen können alle in der
Enum Klasse DBObjectType definierten Einträge angegeben werden. Zum Beispiel
SCHEMA, TABLE, COLUMN und so weiter. Diese Namen können gross oder klein sowie
in Ein- oder Mehrzahl geschrieben werden. Zusätzlich gibt es auch noch das Schlüsselwort
ALL, wenn man alle Datenbankobjekttypen spezifizieren möchte.
59
6.4 Plug-ins
{Bedingung}: Der WHERE Abschnitt ist gänzlich optional. Falls er aber angegeben
wird, kann über Bedingungen die Auswahl von Datenbankobjekten, neben den zuvor definierten Typen, weiter beschränkt werden. Mehrere Bedingung können über AND verknüpft
werden, wobei eine einzelne Bedingung die Form hat:
[name|qname|path|tag][=|!=]{Text}
Durch eine Bedingung kann man Datenbankobjekte mit bestimmten Eigenschaften für die
Transformation auswählen oder von ihr ausschliessen. So können Datenbankobjekte anhand
von ihrem Namen, qualifiziertem Namen, Pfad oder vorhandenen Tags gefiltert werden.
Wenn man nach Namen oder Pfaden sucht, wird der {Text} als regulärer Ausdruck interpretiert. Wenn man hingegen nach Tags sucht wird der {Text} als einfacher Name eines Tags
angesehen.
Wie erwähnt, kann man mit dem Kommentar-Transformator nicht nur Kommentare verändern, sondern zusätzlich bietet er auch die Möglichkeit allgemeine Eigenschaften zu Datenbankobjekten hinzuzufügen. Mit allgemeinen Eigenschaften sind die Eigenschaften in der
DBObjectInfo
Schnittstelle
gemeint,
welche
mit
den
Methoden
addProperty(String name, String value) und addPropertyDBObjectReference(String name, String dbobjRef) gesetzt werden können.
Syntax für Eigenschaft-Transformation-Statements:
ADD PROPERTY [REFERENCE] {Property-Name} = {Property-Value}
[FROM|INTO] {Datenbankobjekttypen}
[WHERE {Bedingungen}];;;
{Property-Name} bezeichnet den Name der Eigenschaft und {Property-Value}
bezeichnet den Wert der Eigenschaft. In beiden Teilen sind die selben Ersetzungsmechanismen wie in {Kommentar} verfügbar. Die restlichen Teile der Syntax sind identisch mit
der von Kommentar-Transformation-Statements.
Auf den ersten Blick lässt sich eventuell nicht direkt erkennen, welche Möglichkeiten dieses
Transformator-Plug-in einem Benutzer bieten kann. Es erscheint, als ob nur Kommentare
geändert werden könnten. Was richtig und falsch ist. Durch den Umstand, dass Kommentare
auch Tags enthalten können und es spezielle Tags, wie @omit oder @omitInOverview gibt,
eröffnen sich aber vielseitige Möglichkeiten, um neben dem Inhalt auch auf dem Umfang einer Dokumentation Einfluss zu nehmen.
60
6 Implementierung
Zum Beispiel können mit dem CommentTransformer Plug-in die vorhandenen Datenbankobjekte gefiltert werden, um so beispielsweise Datenbanksysteme spezifische Datenbankobjekte von der Dokumentation auszuschliessen.
Ebenfalls können mit Hilfe des CommentTransformer Plug-in Datenbankentwurfsmuster
unterstützt werden. Als Beispiel hierfür kann das in der sesamDB zum Einsatz kommende
Historisierungsrelations-Entwurfsmuster unterstützt werden.
Die Kommentar-Transformation-Statements für die Unterstützung des Historisierungsrelation-Entwurfsmusters:
ADD COMMENT {@omitInOverview}
INTO tables
WHERE name=.*_old AND tag!=omitInOverview;;;
ADD COMMENT <font color="red">History relation:</font>
{@link TABLE:REPLACE_FUNC([DBOBJECT_QNAME], _now, _old)
REPLACE_FUNC([DBOBJECT_NAME], _now, _old)}
INTO tables
WHERE name=.*_now;;;
ADD PROPERTY REFERENCE History relation =
TABLE:REPLACE_FUNC([DBOBJECT_QNAME], _now, _old)
INTO tables
WHERE name=.*_now;;;
Das erste Statement bewirkt, dass bei alle Relationen deren Namen auf „_old“ enden und
die nicht schon einen „omitInOverview“-Tag besitzen ein „omitInOverview“-Tag hinzugefügt wird. Das zweite Statement fügt bei allen Relationen, deren Namen auf „_now“ endet,
einen zusätzlichen Kommentar ein. Dieser angehängte Kommentar enthält einen Link auf
die korrespondierende Historisierungs-Relation. Dazu ist es notwendig mit Hilfe des Ersetzungsmechanismus den Namen dieser alten Relation zu konstruieren. Das dritte Statement
ist dem zweiten sehr ähnlich, nur wird der Link auf die korrespondierende alte Relation
nicht im Kommentar, sondern als allgemeine Eigenschaft der Relation gesetzt.
Anschliessend sind noch einige andere Beispiele für praktische Kommentar-Transformation-Statements aufgelistet:
61
6.4 Plug-ins
<!-- Filters out the PostgreSQL catalog schema, containing the all
system objects -->
ADD COMMENT {@omitInOverview}
INTO schema
WHERE name=pg_catalog AND tag!=omitInOverview;;;
<!-- Filters out the PostgreSQL implementation specific triggers
-->
ADD COMMENT {@omitInOverview}
INTO triggers
WHERE name=RI_ConstraintTrigger_.* AND tag!=omitInOverview;;;
<!-- Add an author to all database objects -->
ADD COMMENT {@author "Sascha Nedkoff"}
INTO all
WHERE name=.* AND tag!=author;;;
6.4.4.2 SQL-Reconstructor
Das SQL-Reconstructor-Plug-in wird durch die Klasse SQLReconstructor implementiert. Es wurde entwickelt, weil nicht bei allen Datenbanksystemen die SQL-Create-Statements von Datenbankobjekten ausgelesen werden können, da sie nicht direkt vorhanden
sind. Diese SQL-Create-Statements können aber für Benutzer einer Datenbankdokumentation, die mit SQL vertraut sind, sehr hilfreich sein. Glücklicherweise ist es aber möglich
durch die Analyse anderer Informationen über ein Datenbankobjekt dessen SQL-CreateStatement, wie der Name des Plug-ins schon andeutet, zu rekonstruieren.
Zum Beispiel können bei PostgreSQL Datenbanksystemen nur für einige Datenbankobjekttypen die SQL-Create-Statements direkt aus dem Datenbankschema ausgelesen werden. Für
andere wichtige Datenbankobjekttypen, wie Schemas, Relationen, Spalten, Typumwandlungen und die Datenbank selbst, sind keine SQL-Create-Statements vorhanden. Deshalb besitzt dieses Plug-in die Fähigkeit für genau diese Datenbankobjekttypen ihre SQL-CreateStatements zu rekonstruieren.
Dieses Plug-in könnte aber ohne grossen Aufwand erweitert werden, um SQL-Create-Statements für alle Datenbankobjekttypen zu rekonstruieren. Dann kann es noch allgemeiner eingesetzt werden, um je nach Datenbanksystem, die fehlenden SQL-Create-Statements zu rekonstruieren und sie im Datenmodell zu speichern.
6.4.4.3 View-Properties-Setter
Das View-Properties-Setter-Plug-in ist ein relativ einfaches Plug-in, welches durch die
62
6 Implementierung
Klassse ViewPropertiesSetter implementiert wurde. Der Grund für die Entwicklung
ist, dass im Datenbankschema von PostgreSQL Datenbanksystemen einige Eigenschaften
von Sichten nicht direkt verfügbar sind. Das heisst man kann sie nicht einfach auslesen sondern man muss sie aus anderen ausgelesenen Informationen ableiten. Bei diesen Eigenschaften handelt es sich um die auf einer Sicht erlaubten Aktionen, also um Angaben, ob es auf
einer Sichten möglich ist Tupel einzufügen, zu ändern oder zu löschen. Um aber im PostgreSQL-Input-Plug-in keinen zusätzlichen Aufwand betreiben zu müssen, um diese Informationen zu erhalten, wurde es als wesentlich einfacher angesehen ein kleines Transformator-Plug-in zu implementieren, welches in einem späteren Zeitpunkt diese Information über
Sichten hinzufügt, indem es diese aus anderen Information ableitet.
Das View-Properties-Setter-Plug-in analysiert die für eine Sicht definierten Regeln und deren Event-Typ. Aus dem Vorhandensein einer Regel und ihrem Event-Typ erkennt das Plugin, dass eine entsprechende Aktion auf der Sicht möglich ist und kann so diese Information
über die Sicht zu den anderen Information über die Sicht hinzufügen. Wenn also zum Beispiel auf einer Sicht eine Regel definiert wurde deren Event-Typ „INSERT“ lautet, bedeutet
dies dass Aktionen zum Einfügen von Tupeln in die Sicht erlaubt sind. Ist hingegen keine
solche Regel vorhanden, sind auch keine Einfüge-Aktionen erlaubt. Für detailliertere Informationen zu diesem Thema wird auf die PostgreSQL Dokumentation über „Rewrite Rules“
verwiesen [PostgreSQL07].
Um zu zeigen wie einfach dieses Plug-in aufgebaut ist und zur Illustration, wie einfach es
sein kann ein Transformator-Plug-in zu implementieren, ist in Abbildung 8 der gesamt JavaCode des implementierten View-Properties-Setter Plug-ins abgebildet.
Das Plug-in erbt von der abstrakten Klasse AbstractTransformer. Dadurch kann im
Vergleich zur direkten Implementierung der TransformatorPlugin Schnittstelle viel
Arbeit eingespart werden. Denn es entfällt der Aufwand, um die allgemeinen Methoden eines Transformator-Plug-ins zu implementieren, weil auf die generische Implementierung
der AbstractTransformer Klasse zurückgegriffen werden kann. Es musste nur die
Methode transform() überschrieben werden, um dem Plug-in die angesprochene Funktionalität zu verleihen.
63
6.4 Plug-ins
package org.sesam.dbdoc.transform;
import org.sesam.dbdoc.*;
public class ViewPropertiesSetter extends AbstractTransformer {
public ViewPropertiesSetter() {
super();
}
public RootInfo transform(RootInfo root) throws
PluginException {
RootInfo rootinfo = super.transform(root);
}
}
for (ViewInfo view : rootinfo.getAllViews()) {
for (RuleInfo rule : view.getRules()) {
switch (rule.getEventType()) {
case 'U':
view.setIsUpdatable(true);
break;
case 'I':
view.setIsInsertable(true);
break;
case 'D':
view.setIsDeletable(true);
break;
default:
break;
}
}
}
return rootinfo;
Abbildung 8: Kompletter Java-Code des ViewPropertiesSetter-Plug-ins
6.4.4.4 Simulated Constraint Analyser
Das Simulated-Constraint-Analyser-Plug-in ist ein Transformator-Plug-in das speziell für
die Unterstützung eines in der sesamDB verwendeten Entwurfsmusters und damit für eine
bessere Dokumentation der sesamDB implementiert wurde.
In der sesamDB werden viele Einschränkungen auf Relationen und Spalten nicht mit normalen Einschränkungen, sondern mit Triggerfunktionen realisiert. Und zwar deshalb, weil
Einschränkungen nicht über alle Relationen einer Vererbungshierarchien betrachtet werden,
sondern nur auf einer Relation wirksam sind. So kann mit Einschränkungen allein zum Bei64
6 Implementierung
spiel nicht sichergestellt werden, dass eine Primärschlüssel über mehrere Relationen in der
Vererbungshierarchie eindeutige ist. Zusätzlich kann es einfacher sein eine Einschränkung
für alle Relationen gemeinsam mit einer Triggerfunktionen zu realisieren, als für jede Relation einzeln eine Einschränkung zu definieren.
Durch diesen Mechanismus entsteht aber ein Problem für die Dokumentation dieser Relationen. Denn über solche durch Triggerfunktionen realisierte Einschränkungen gibt es im Datenbankschema keine direkten Informationen. Deshalb können diese Informationen über
Einschränkungen auch nicht ausgelesen werden und folglich auch keine entsprechenden
Einschränkungsobjekte im Datenmodell erzeugt werden. Diese Einschränkungsobjekte wären aber wichtig, um den Umstand von vorhandenen Einschränkungen auf einer Relation zu
dokumentieren. Deshalb wurde dieses Transformator-Plug-in entwickelt, welches durch die
Analyse von Triggerfunktionen diese Informationen über Einschränkungen rekonstruieren
kann und um so die entsprechenden Einschränkungsobjekte im Datenmodell zu erzeugen,
wodurch die gewonnenen Informationen repräsentiert und in der Dokumentation verwendet
werden können.
65
7 Tests
7 Tests
7.1 Performance
Die Ausführungsgeschwindigkeit spielt für diese Anwendung zwar nur eine untergeordnete
Rolle, trotzdem ist sie nicht völlig vernachlässigbar, da es natürlich wünschenswert ist, dass
die Dokumentation so schnell wie möglich generiert wird und zur Verfügung steht. Hauptsächlich hängt die Ausführungszeit der Anwendung von der Grösse der zu dokumentierenden Datenbank ab. Genauer gesagt von der Anzahl zu dokumentierenden Datenbankobjekten. Je mehr Datenbankobjekte vorhanden sind, desto mehr Informationen müssen ausgelesen, verarbeitet und wieder ausgegeben werden.
Als Testumgebung diente ein Desktop Computer mit einem Intel Pentium 4 Prozessor mit
1.60GHz und 768 MB Arbeitsspeicher. Als Betriebssystem kam „openSUSE 10.2“ zum
Einsatz und ausgeführt wurde die Anwendung in der Eclipse Entwicklungsumgebung mit
dem JRE 1.5.
Für die eigentlich Durchführung der Performance-Tests wurde auf einem PostgreSQL Datenbanksystem eine Testdatenbank aufgesetzt, deren Umfang durch Hinzufügen von neuen
Relationen kontinuierlich vergrössert wurde. Nach jedem Hinzufügen von neuen Relationen
wurde die Anwendung erneut ausgeführt und die Zeiten für die Ausführung von einzelnen
Plug-ins sowie die Gesamtzeit gemessen.
Die für den Test verwendeten Relationen haben alle dieselbe Struktur wie sie in Abbildung
9 zu sehen ist. Sie haben 4 Spalten wovon die ersten zwei „Integer“ und die zweiten zwei
„Text“ als Datentyp haben. Die erste Spalte ist als Primärschlüssel und die zweite als eindeutige („unique“) definiert. Dies bedeutet für jede Relation sind zwei Einschränkungen definiert.
66
7 Tests
CREATE TABLE test_table_1
(
col_1 bigint NOT NULL,
col_2 bigint NOT NULL,
col_3 text,
col_4 text,
CONSTRAINT pkey_con PRIMARY KEY (col_1),
CONSTRAINT unique_con UNIQUE (col_2)
)
WITHOUT OIDS;
Abbildung 9: SQL Create Statement für Test-Relationen
In PostgreSQL wird automatisch für jede Relation zusätzlich ein Datentyp erzeugt, welcher
den Zeilen-Datentyp dieser Relation repräsentiert. Ebenfalls wird in PostgreSQL für jeden
Primärschlüssel und jede Unique-Einschränkung ein Index erzeugt. So werden für jede Relation insgesamt 10 Datenbankobjekte erzeugt. Ein Relation-, ein Datentyp-, vier Spalten-,
zwei Einschränkungs-, und zwei Index-Objekte.
Die Resultate der Tests für Datenbanken mit unterschiedlicher Grösse:
Anzahl
Relationen Objekte
0
3026
1
3036
10
3126
100
4026
1000 13026
2000 23026
3000 33026
Zeit in Sekunden
Einlesen Verlinkung Transformation Ausgabe
5,7
0,7
0,02
6,1
5,7
0,7
0,03
6,1
5,7
0,7
0,05
6,5
6,7
1,0
0,30
8,1
13,2
11,9
0,60
24,4
20,4
38,2
0,80
42,5
27,6
80,0
1,45
62,8
Total
13,4
13,4
13,8
17,1
51,0
102,9
172,9
HTML-Ausgabe
Grösse
Dateien
13,9 MB
3128
14,0 MB
3143
14,5 MB
3260
19,6 MB
4430
71,7 MB
16130
130,0 MB
29130
188,7 MB
42130
Tabelle 6: Detaillierte Ausführungszeiten für Datenbanken unterschiedlicher Grösse
Aus den Testresultaten von Tabelle 6 sich herauslesen, dass die Zeiten für das Auslesen der
Informationen sowie die Generierung der Ausgabe ziemlich linear anwachsen. Aber die Zeiten für die Verlinkung der Datenbankobjekte überproportional ansteigen. Bei einer Anzahl
von 2000 und 3000 Relationen sind die hohen Zeiten für die Verlinkung hauptsächlich auf
die sehr grosse Anzahl von Objekten des gleichen Typs zurückzuführen. Bei 3000 Relationen existieren 12000 Spalten, 6000 Einschränkungen und 6000 Indexes. Und so benötigen
einige Suchoperationen, wenn sie alle Objekte eines Typs durchsuchen müssen, immer län67
7.1 Performance
ger je mehr Objekte existieren.
Gesamthaft lässt sich sagen, dass die Ausführungszeiten für kleine und mittelgrosse Datenbanken als angemessen angesehen werden können. Nur bei übergrossen Datenbanken, mit
sehr vielen Objekten des selben Typs, werden die Zeiten relativ lang, sie sind aber immer
noch akzeptabel.
7.2 JUnit
Mit Hilfe des JUnit Frameworks17 zum automatisiertem Testen von Code-Einheiten wurden
verschiedene Tests implementiert. Es wurde als besonders wichtig angesehen, automatisierte
Test für diejenigen Teile der Anwendung zu erstellen, welche Daten verarbeiten, die vom
Benutzer eingegeben werden. Solche Daten sind durch ihre Herkunft bedingt in gewisser
Weise unvorhersehbar und beliebig. Zu den wichtigsten vom Benutzer eingegebenen Daten
zählen die benutzerdefinierten Kommentare für Datenbankobjekte. Da diese Kommentare
Tags enthalten können, müssen sie speziell analysiert und weiterverarbeitet werden.
So wurden JUnit-Tests für den Kommentar-Parser, die Kommentar-Klasse und die TagKlassen implementiert. Diese Tests sind darauf ausgelegt den Parser auf Korrektheit sowie
die Erstellung und Konfiguration von Kommentar- und Tag-Objekten zu überprüfen. Zusätzlich wird das Verhalten bei falsch formatierten Kommentaren und Tags getestet.
Zu anderen vom Benutzer gemachte Angaben zählen die Angaben in der Konfigurationsdatei und in der Tag-Definitionsdatei. Bei beiden handelt es sich um XML-Dateien für welche
ein XML-Schema definiert wurde, um die Korrektheit beim Einlesen der Datei zu prüfen.
17 http://www.junit.org
68
8 Weiterführende Arbeiten
8 Weiterführende Arbeiten
In der vorliegenden Arbeit wurde eine Applikation zur Dokumentation von Datenbanken erstellt. Diese Applikation kann einerseits durch den für diesen Zweck vorgesehenen Mechanismus der Plug-ins erweitert werden und andererseits können auch schon vorhandene Plugins erweitert werden. Durch die Erstellung neuer Plug-ins kann der Applikation in verschiedenen Bereichen weitere Funktionalität verliehen werden oder es können zusätzliche Datenbanksysteme angebunden werden.
Nachfolgend werden einige denkbare Erweiterungen detaillierter beschrieben.
8.1 Graphische Benutzeroberfläche (GUI)
Eine für den Benutzer sehr angenehme Erweiterung wäre sicherlich das Hinzufügen einer
graphischen Benutzeroberfläche. Hierfür gibt es grundsätzlich zwei Varianten. Es könnte
eine allgemeine graphische Oberfläche für die Hauptapplikation zur Steuerung des Ablaufs
und der Konfiguration der Plug-ins erstellt werden. Das ähnliche Möglichkeiten zur Konfiguration bietet würde, wie die zurzeit verwendete Methode zur Konfiguration über die
Kommandozeile und die spezielle XML-Datei. Als zweite Variante könnten einzelne Plugins ihre eigene graphische Oberfläche zur Konfiguration und Interaktion mit dem Benutzer
anbieten.
Beispielsweise könnte ein Transformator-Plug-in eine graphische Oberfläche anbieten, welche alle vorhandenen Datenbankobjekte anzeigt und es erlaubt sie nach Typen oder auch
einzeln an- beziehungsweise abzuwählen, um so genau zu bestimmen welche Objekte dokumentiert werden sollen. Ebenfalls könnten über eine solche Benutzeroberfläche die Kommentare und Eigenschaften von Datenbankobjekten geändert werden. Und eventuell könnte
das Transformator-Plug-in die Änderungen in den Kommentaren sogar zurück in die Datenbank speichern.
Eine sehr ähnlich Möglichkeit existiert bereits mit dem „Comment-Transformer“ Plug-in.
Dieses erlaubt ebenfalls die Auswahl der zu dokumentierenden Objekte und Änderung der
Kommentare sowie das Hinzufügen neuer Eigenschaften. Allerdings funktioniert dies über
die Angabe von speziellen Transformator-Statements, die als Parameter dem Plug-in übergeben werden. Eine graphische Oberfläche wäre hier intuitiver und benutzerfreundlicher.
69
8.2 Weitere Datenbankanbindungen
8.2 Weitere Datenbankanbindungen
Das Einsatzgebiet der Applikation kann mit Hilfe des Plug-in Mechanismus sehr einfach
weiter ausgedehnt werden. Momentan existiert nur ein Input-Plug-in für die Anbindung von
PostgreSQL Datenbanksystemen, aber es können zusätzliche Input-Plug-ins entwickelt werden, um die Anbindung zu anderen relationalen Datenbanksystemen zu ermöglichen. Ein
solches Plug-in kann entweder speziell für ein bestimmtes Datenbanksystem und dessen Datenkatalog entwickelt werden oder es könnte allgemeiner gehalten werden und über das im
SQL Standard definierte „Information-Schema“ Informationen aus der Datenbank auslesen.
Ein solches Input-Plug-in könnte dann mit allen Datenbanksystemen verwendet werden, die
das „Information-Schema“ gemäss dem SQL Standard implementieren. Um noch allgemeiner zu sein, könnte ein Input-Plug-in die in der Java-Datenbankschnittstelle JDBC18 angebotenen Methoden verwenden, um Informationen über die Datenbank auszulesen. Somit könnten alle Datenbanksysteme die einen JDBC Treiber zur Verfügung stellen, dokumentiert
werden.
8.3 Weitere Ausgabeformate
Zusätzlich zu dem momentan existierendem Output-Plug-in zur Erstellung einer HTML-Dokumentation wären viel andere Formate für die Ausgabe der Dokumentation vorstellbar.
Denkbar wären zum Beispiel eine Ausgabe im PDF oder auch im ODF beziehungsweise im
MS Word Format. Weiter Ausgabeformate könnten XML oder normaler Text sein.
Zusätzlich zur Ausgabe der eigentliche Dokumentation in verschiedenen Dateiformaten sind
auch andere Arten von Ausgaben denkbar. Beispielsweise wäre eine Art Analyse-Ausgabe,
die Auskunft über Verbindungen, Verbindungsgrade oder Abhängigkeiten zwischen Datenbankobjekten gibt. Diese Ausgabe könnte ihrerseits natürlich wieder in verschiedenen Ausgabeformaten ausgegeben werden. Oder es könnte ein Output-Plug-in entwickelt werden,
dass ein „SQL Create Script“ für die Datenbank generieren kann.
Ebenfalls interessant wären Ausgaben in speziellen Formaten, die in andere Programme geladen werden können. Zum Beispiel für ER-Diagramm Editoren oder allgemeine Visualisierungswerkzeuge für Graphen.
8.4 Erweiterung des Datenmodells
Ebenfalls möglich wäre eine Erweiterung des Datenmodells, um mehr Daten über einzelne
Datenbankobjekte zu speichern. Obwohl schon generische Methoden für die Speicherung
18 Java Database Connectivity
70
8 Weiterführende Arbeiten
von beliebigen Datenbankobjekt-Informationen und -Referenzen existieren, könnten spezielle Methoden für spezifische Informationen hinzugefügt werden. Durch das explizite Hinzufügen von speziellen Methoden würde dann klar ausgezeichnet werden, welche Informationen in den verschiedenen Datenbankobjekttypen noch vorhanden sind. Eine Idee wäre
zum Beispiel Informationen über die gegenseitigen Abhängigkeiten von Datenbankobjekten
hinzuzufügen. Natürlich müssten dann auch die Input-Plug-ins und Output-Plug-ins erweitert werden, um diese zusätzlichen Informationen aus der Datenbank auszulesen, beziehungsweise in der generierten Dokumentation auszugeben.
8.5 Weitere Transformatoren
Weitere Transformator-Plug-ins sind vor allem sinnvoll, um auf spezielle Gegebenheiten
von spezifischen Datenbanken oder Datenbanksystemen eingehen zu können. Transformatoren erlauben so differenziert auf spezielle Situationen zu reagieren. Deshalb bieten sich
Transformator-Plug-ins geradezu an, um spezielle Datenbankentwurfsmuster zu unterstützen und sie in der Dokumentation angemessen dokumentieren zu können.
8.6 Persistente Speicherung der Informationen über
Datenbankobjekte
Falls man die Applikation um die Fähigkeit erweitern würde, alle Informationen über Datenbankobjekte die im Datenmodell vorhanden sind persistent zu speichern, eröffneten sich
neue Möglichkeiten in der Anwendung der Applikation. Ist einmal die Fähigkeit gegeben
den aktuellen Zustand des Datenmodells persistent, zum Beispiel in einer XML-Datei zu
speichern, kann die Applikation zu verschiedenen Zeitpunkten ausgeführt werden und auf
ältere Zustände zurückgreifen.
Eine denkbare Lösung hierfür wäre die Serialisierung aller im Datenmodell vorhandenen
Objekte, inklusive ihrer Zustände, zu implementieren. Ein Transformator-Plug-in würde
dann die tatsächliche Serialisierung alle Datenbankobjekte vornehmen und eine weiteres
Transformator-Plug-in könnte zu einem späteren Zeitpunkt die Daten wieder einlesen, um
den Zustand des Datenmodells zu rekonstruierten. Daneben müssten aber zusätzlich Änderungen in der Hauptapplikation und der Schnittstelle für Output-Plug-ins gemacht werden,
damit mehr als eine Instanz von einem Datenmodell übergeben werden könnte. Wenn dann
aber einem Output-Plug-in mehrere Instanzen eines Datenmodells zur Verfügung stehen, ergeben sich die neuen Möglichkeit in der Ausgabe. So könnte beispielsweise eine Art
„Diff“-Ausgabe generiert werden, also eine Ausgabe, welche die Unterschiede zwischen
zwei Instanzen des Datenmodells und damit zwischen zwei verschiedenen Datenbankzu71
8.6 Persistente Speicherung der Informationen über Datenbankobjekte
ständen dokumentiert. Eine solche Ausgabe könnte gut eingesetzt werden, um die Änderungen in Datenbanken über die Zeit zu dokumentieren. Ebenfalls denkbar wäre eine inkrementelle Generierung der Dokumentation, so könnten nur neu hinzugekommene oder geänderte
Datenbankobjekte in eine schon vorhandene Dokumentation eingefügt werden.
72
9 Zusammenfassung und Schlussfolgerungen
9 Zusammenfassung und
Schlussfolgerungen
In dieser Arbeit wurde eine Anwendung zur Dokumentation von Datenbanken entworfen
und implementiert, welche über den Zugriff auf benutzerdefinierte Kommentare und Schemainformationen in der Lage ist eine HTML-Dokumentation der Datenbank zu generieren.
Dazu wurden zuerst die in diesem Bereich schon vorhandenen Programme untersucht und
deren Stärken und Schwächen identifiziert. In einem zweiten Schritt konnten aus diesen Erkenntnissen und inspiriert von Javadoc, die allgemeinen Anforderungen an eine Anwendung
zur Dokumentation von Datenbanken abgeleitet und spezifiziert werden.
Durch den Entwurf eines generischen Datenmodells, zur temporären Speicherung von Datenbankinformation sowie einer Plug-in Architektur zur flexiblen Konfiguration der Anwendung wurde versucht diesen Anforderungen gerecht zu werden.
Während der Implementierung zeigte sich, dass durch die Plug-in Architektur eine einfache
aber sehr flexible Möglichkeit geschaffen werden konnte, um grundsätzlich verschiedene
Datenbankanbindungen und verschiedene Ausgabeformate zu ermöglichen. Mit dem
HTML-Plug-in ist es gelungen eine Komponente zu implementieren, die in der Lage ist eine
strukturierte und aussagekräftige HTML-Dokumentation zu generieren, welche auch tatsächlich Potential hat in der Zukunft eingesetzt werden zu können. Die HTML-Ausgabe
kann flexibel konfiguriert werden um sie verschiedenen Bedürfnissen anzupassen.
Das weite Feld der Datenbankdokumentation in Verbindung mit der Plug-in Architektur bietet sich gerade zu an, um die Anwendung mit neuen Plug-ins zu erweitern. Es könnten neue
Input-Plug-ins erstellt werden, um zusätzliche Datenbankanbindungen zu realisieren oder es
könnten neue Output-Plug-ins implementiert werden, um zusätzliche Ausgabeformate anbieten zu können.
Zusätzlich konnten mit der Plug-in Architektur und Transformator-Plug-ins eine attraktive
Möglichkeit für die Unterstützung von Datenbankentwurfsmuster geschaffen werden. Standardmässig werden von der Anwendung schon einige Transformator-Plug-ins angeboten,
wobei besonders der Kommentar-Transformator als generischer Transformator eingesetzt
werden kann um Entwurfsmuster zu dokumentieren. Zusätzlich können in der Zukunft neue
Transformator-Plug-ins entwickelt werden, um so komplexere oder sehr spezifische Entwurfsmuster zu unterstützen.
Durch ein Konzept für Tags wird es, wie im Bereich der Dokumentationswerkzeuge für Pro-
73
9 Zusammenfassung und Schlussfolgerungen
grammcode schon üblich, möglich die benutzerdefinierten Kommentare zu formatieren und
spezielle Informationen auszuzeichnen sowie Verweise auf andere Objekte zu definieren.
Zusätzlich erlauben spezielle Tags, Kommentare nur für bestimmte Benutzergruppen zu
spezifizieren. Durch eine geeignete Kombination dieser Tags mit anderen Konfigurationsmöglichkeiten, wie den Kommentare-Transformator, wird es möglich die Dokumentation
für bestimmte Benutzergruppen zu individualisieren.
74
Literaturverzeichnis
[ApexSQLDoc]:
Apex LLC, ApexSQL Doc, ,
http://www.apexsql.com/datasheets/ApexSQL_doc_datasheet.pdf
[DBScribe]:
Leadum Software, DBScribe, ,
http://www.leadum.com/product.datasheet.php?prod_id=18
[EinfJava]:
Klein, Robert, Einführung in JavaDoc, 2005,
http://daxue.xyzzy.de/javadoc.pdf
[Gamma04]:
Gamma, Erich [et al.], Entwurfsmuster: Elemente
wiederverwendbarer objektorientierter Software, 2004
[Glinz01]:
Glinz, Martin, Vorlesungsskript in Software Engineering 1, 2001
[MerkblattJavaDoc]: Merkblatt JavaDoc, , http://qeinformatik.uibk.ac.at/lehre/ss04/se4/download/merkblaetter/
JavaDoc.pdf
[PluginArch]:
Hansen, H. Keld, Plug-in to Reusability in Java, ,
http://javaboutique.internet.com/tutorials/keldplugins/
[PostgreSQL07]:
PostgreSQL, PostgreSQL 8.2.6 Documentation, 2007,
http://www.postgresql.org/docs/8.2/static/index.html
[Sommervile01]:
Ian Sommerville, Software Documentation, 2001,
http://www.literateprogramming.com/documentation.pdf
[SQLDoc]:
Redgate Software, SQL Doc, 2008, http://www.redgate.com/products/SQL_Doc/SQL_Doc.pdf
[SqlSpec]:
Elsasoft, SqlSpec, , http://www.elsasoft.org/
[SunJavaDoc]:
Sun Microsystems, Sun Microsystems Javadoc Tool, ,
http://java.sun.com/j2se/javadoc/
[TreeMenu]:
75
Morten, JavaScript Tree Menu, 2008, http://www.treemenu.org/
Abbildungsverzeichnis
Abbildung 1: Ausschnitt aus der Schnittstellenhierarchie.....................................................24
Abbildung 2: Plug-in Typen...................................................................................................30
Abbildung 3: Tag-Schnittstellen.............................................................................................39
Abbildung 4: Tag-Schnittstellen und Tag-Klassen.................................................................42
Abbildung 5: Plug-in Implementierungen..............................................................................48
Abbildung 6: Implementierungsvererbung im HTML-Output-Plug-in.................................52
Abbildung 7: Generierte HTML-Dokumentation..................................................................53
Abbildung 8: Kompletter Java-Code des ViewPropertiesSetter-Plug-ins..............................62
Abbildung 9: SQL Create Statement für Test-Relationen......................................................64
76
Tabellenverzeichnis
Tabelle 1: Javadoc Tags..........................................................................................................12
Tabelle 2: Vordefinierte Tags..................................................................................................44
Tabelle 3: Optionen des Standard-Model-Plug-ins................................................................49
Tabelle 4: Optionen des PostgreSQL-Input-Plug-ins.............................................................50
Tabelle 5: Optionen des HTML-Output-Plug-ins..................................................................55
Tabelle 6: Detaillierte Ausführungszeiten für Datenbanken unterschiedlicher Grösse.........65
77

Similar documents