Technische Dokumentation - Joinup

Technische Dokumentation
xdomea-Viewer
Version
Version 1.1 , 22.12.2009
Sächsischen Staatsministerium
der Justiz und für Europa
Hospitalstraße 7
01097 Dresden
4. Januar 2010
Seite 2/27
xdomea-Viewer
Dokumentenhistorie
Version
Datum
Autor
Kommentar
0.9
27.11.2009
Dominique
Lopes
Initiale Erstellung
1.0
03.12.2009
Dominique
Lopes
Überarbeitung nach Anmerkungen
vom Auftraggeber
1.1
22.12.2009
Dominique
Lopes
Abschnitt „3.2 Einrichtung der
Entwicklungsumgebung“
überarbeitet, neue Abschnitte „1
Vorwort“ und „3.5 Zusammenstellen
der Gesamtanwendung“
hinzugefügt
4. Januar 2010
Seite 3/27
xdomea-Viewer
Inhaltsverzeichnis
1
Vorwort
5
2
Funktionsbeschreibung
6
2.1
Anwendungsfälle
6
2.2
Prozesse
8
3
technische Umsetzung
10
3.1
Voraussetzungen zum Entwickeln
10
3.2
3.2.1
3.2.2
Einrichtung der Entwicklungsumgebung
Einrichtung der Eclipse-Projekte mit Maven
Einrichtung der Target-Plattform
11
11
11
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
Weiterentwicklung des Viewer-Frameworks
technische Basis
Modularisierung
Beschreibung des Projekts: xdomea-Viewer-core
Beschreibung des Projekts: xdomea-Viewer-gui
Erweiterungsmöglichkeiten
12
12
12
13
19
20
3.4
3.4.1
3.4.2
Weiterentwicklung der XSL-Templates
CSS-Konventionen
Einsatz von JavaScript
21
22
23
3.5
3.5.1
3.5.2
3.5.3
3.5.4
Zusammenstellen der Gesamtanwendung
Änderungen am dem XML-Schema der Konfigurationsdatei
Änderungen am Quellcode des Projekts xdomea-Viewer-core
Änderungen an den XSL-Templates
Änderungen an der Oberfläche (Eclipse-RCP)
25
25
25
26
26
4
Lizensierung
27
xdomea-Viewer
4. Januar 2010
Seite 4/27
Abbildungsverzeichnis
Abbildung 1: Anwendungsfalldiagramm für den xdomea-Viewer ................................ 6
Abbildung 2: Aktivitätsdiagramm des xdomea-Viewers ............................................... 8
Abbildung 3: Aufteilung des xdomea-Viewers in Module........................................... 10
Abbildung 4: Klassendiagramm Paket de.xoev.xdomea.viewer.configuration .......... 14
Abbildung 5: Schema der Konfigurationsdatei........................................................... 16
Abbildung 6: Klassendiagramm Paket de.xoev.xdomea.viewer.modules ................. 17
Abbildung 7: Klassendiagramm Paket de.xoev.xdomea.viewer.modules.validation . 18
Abbildung 8: logische Aufteilung der HTML-Darstellung einer xdomea-Nachricht.... 21
Abbildung 9: barrierefreie Darstellung einer xdomea-Nachricht ................................ 23
xdomea-Viewer
4. Januar 2010
Seite 5/27
1 Vorwort
Dieses Dokument beschreibt die Funktionsweise, technische Umsetzung und Lizensierung
des xdomea-Viewers. Es richtet sich an Programmierer, die den xdomea-Viewer anpassen
oder zu dessen weiteren Entwicklung beitragen möchten. Um mit diesem Dokument
arbeiten zu können werden Kenntnisse in der XSLT- und Java-Entwicklung, mit der Eclipse
RCP Plattform und Maven 2 vorausgesetzt. Die Beschreibungen zur technischen
Umsetzung und insbesondere zur Einrichtung der Entwicklungsumgebung und des Exports
der Anwendung gehen daher nur bedingt auf die Verwendung dieser SoftwareKomponenten und damit in Zusammenhang stehenden Quellcode-Bestandteilen ein. Sofern
neue oder vorhandene XSL-Templates (weiter)entwickelt werden, sind ebenfalls Kenntnisse
der jeweiligen xdomea-Spezifikation notwendig.
4. Januar 2010
Seite 6/27
xdomea-Viewer
2 Funktionsbeschreibung
Der xdomea-Viewer ist eine Anwendung zur Visualisierung der Inhalte einer xdomeaNachricht.
Dazu müssen i. W. drei Funktionen nacheinander ausgeführt werden:
•
•
•
2.1
die Validierung der anzuzeigenden xdomea-Nachricht
die Transformation der XML-Nachricht in eine darstellbare Form
die Visualisierung der xdomea-Inhalte in einem nutzerfreundlichen Format
Anwendungsfälle
Die folgende Abbildung zeigt das Anwendungsfall-Diagramm des xdomea-Viewers:
Abbildung 1: Anwendungsfalldiagramm für den xdomea-Viewer
Die Kernfunktionalität des xdomea-Viewers ist die benutzerfreundliche Darstellung
einer xdomea-Nachricht. Dies wird in Abbildung 1 durch den Anwendungsfall
„xdomea-Nachricht visualisieren“ dargestellt. Der Anwendungsfall gliedert sich in drei
untergeordnete Anwendungsfälle:
Zunächst muss die aus einer ZIP-Datei bestehende xdomea-Nachricht extrahiert und
in ein vorkonfiguriertes Arbeitsverzeichnis kopiert werden (Anwendungsfall: „xdomeaNachricht extrahieren“).
Anschließend werden die kopierten Daten unter mehreren Gesichtspunkten überprüft.
xdomea-Viewer
4. Januar 2010
Seite 7/27
Zunächst erfolgt eine formale Prüfung der vorliegenden xdomea-ZIP-Datei. Dazu wird
die Ordnerstruktur innerhalb der xdomea-ZIP-Datei überprüft. Weiterhin wird der
Dateiname gegen einen regulären Ausdruck geprüft um sicherzustellen, dass eine
xdomea-konforme Datei vorliegt.
Ein zweiter Validierungsschritt prüft, ob die XML-Datei mit den Metadaten für xdomea
wohlgeformt ist. Ist dies der Fall, dann wird die XML-Datei gegenüber der
konfigurierten xdomea-Spezifikation/Schema auf Validität geprüft. Abschließend
erfolgt die Prüfung auf Vollständigkeit, in dem die Existenz der in der XML-Datei
referenzierten Dokumente überprüft wird.
Danach wird die xdomea-Nachricht mittels XSLT in HTML transformiert und innerhalb
eines Browserfensters eingebettet in die Anwendung angezeigt (Anwendungsfall:
„xdomea-Nachricht transformieren“).
4. Januar 2010
Seite 8/27
xdomea-Viewer
2.2
Prozesse
Mit dem xdomea-Viewer sind die folgenden Aktivitäten ausführbar:
•
•
Arbeitsverzeichnis auswählen
xdomea-Nachricht auswählen und visualisieren
Die Aktivitäten und ihre Einbettung in den gesamten Ablauf der Anwendung werden
im folgenden Diagramm dargestellt:
Abbildung 2: Aktivitätsdiagramm des xdomea-Viewers
xdomea-Viewer
Die xdomea-Nachrichten werden in einem konfigurierbaren Arbeitsverzeichnis
extrahiert und weiterverarbeitet. Daher muss der Benutzer nach dem Start der
Anwendung in einem entsprechenden Dialog ein Arbeitsverzeichnis festlegen.
4. Januar 2010
Seite 9/27
4. Januar 2010
Seite 10/27
xdomea-Viewer
3 technische Umsetzung
Bezüglich der Implementierung wird zwischen dem Viewer-Framework und des
xdomea-Viewer unterschieden. Das Viewer-Framework enthält alle generischen
Komponenten zur Ausführung der o. g. Funktionalitäten. Der xdomea-Viewer baut auf
dem Viewer-Framework auf. Er enthält zusätzlich xdomea-spezifische Dateien und
Konfigurationen zur Umwandlung der XML-Nachrichten.
Abbildung 3: Aufteilung des xdomea-Viewers in Module
3.1
Voraussetzungen zum Entwickeln
Die Entwicklung des xdomea-Viewers erfolgte mit frei verfügbaren Tools. Für die
Weiterentwicklung werden daher genau diese Tools benötigt:
•
•
•
Java Development Kit 5 (http://java.sun.com/products/archive/)
Maven 2 (http://maven.apache.org/download.html)
Eclipse 3.5.1 für RCP/Plug-in Entwickler (http://www.eclipse.org/downloads/)
Zusätzlich werden für den Export der Quellcodes in eine lauffähige StandaloneAnwendung folgende Komponenten benötigt:
•
•
•
eine zweite Installation der Eclipse 3.5.1 für RCP/Plug-in Entwickler
das Delta Pack für Eclipse 3.5.1
das deutsche Babel Language Pack für Eclipse 3.5 (hier genügt
BabelLanguagePack-eclipse-de_[Versionsnummer].zip)
Bitte achten Sie beim Herunterladen der Komponenten auf zueinander passende
Versionsnummern.
4. Januar 2010
Seite 11/27
xdomea-Viewer
Alle Komponenten sind unter http://download.eclipse.org/eclipse/downloads/
erhältlich.
3.2
Einrichtung der Entwicklungsumgebung
Auf dem Entwicklungs-PC muss das JDK und Maven 2 in mindestens den o. g.
Versionen installiert sein. Weiterhin muss die Eclipse-IDE in einen beliebigen Ordner
extrahiert worden sein. Es bietet sich an das M2Eclipse-Plugin zur Installation der
Eclipse-IDE hinzuzufügen. Nutzen Sie hierzu die Eclipse Update-Site
http://m2eclipse.sonatype.org/update/
3.2.1
Einrichtung der Eclipse-Projekte mit Maven
Leider stand zum Zeitpunkt der Implementierung noch kein Maven-Artefakt von
Saxon-HE 9.2.0.3 in einem öffentlichen Maven Repository zur Verfügung. Laden Sie
daher Saxon-HE 9.2.0.3 unter http://saxon.sourceforge.net/ herunter und installieren
Sie es in Ihrem Maven Proxy. Sollten Sie über keinen Maven Proxy verfügen, so
können Sie auch versuchen Saxon-HE 9.2.0.3 direkt in ihrem lokalen Maven
Repository zur Verfügung zu stellen. Nutzen Sie bitte hierzu die bereitgestellten
Dateien und kopieren Sie sie nach {M2_HOME}/net/sf/saxon/saxon/9.2.0.3.
Wechseln Sie in der Konsole in das Verzeichnis des Eclipse-Projekts xdomeaViewer-core. Gehen Sie in das Verzeichnis /conf und führen Sie mvn install
aus. Wechseln Sie nun wieder in das übergeordnete Projektverzeichnis und führen
Sie ebenfalls mvn install aus.
Achtung: die o. g. Reihenfolge muss eingehalten werden!
Fügen Sie die beiden o. g. Eclipse-Projekte nun zu Ihrem Eclipse Workspace hinzu.
Nutzen Sie hierzu jeweils den Import-Assistenten „Existing Projects into Workspace“
der Eclipse-IDE und folgend Sie den Anweisungen auf dem Bildschirm.
3.2.2
Einrichtung der Target-Plattform
Die zusätzlichen Komponenten (zweite Installation der Eclipse RCP Runtime, das
Deltapack und das Language Pack) müssen in einem gesonderten Ordner extrahiert
werden. Aus Gründen der Übersichtlichkeit sollten die Komponenten in einzelne
Ordner extrahiert werden. Sie können aber auch die einzelnen Komponenten
übereinander kopieren. Im weiteren Verlauf dieses Abschnitts wird dieser Ordner mit
{EXPORT_ADDONS} referenziert.
Für den Export der Quellcodes in eine Anwendung wird eine sogenannte TargetPlattform benötigt. Die Target-Plattform wird genutzt um die Abhängigkeiten der
Anwendung zu benötigten Eclipse-Plugins aufzulösen und diese beim Export
4. Januar 2010
Seite 12/27
xdomea-Viewer
zusammenzustellen. Nach der Installation der Eclipse-IDE ist die Target-Plattform
standardmäßig auf das Installationsverzeichnis gesetzt. D. h. für den Export der
Anwendung wird die Entwicklungsumgebung selbst als Target-Plattform genutzt. Da
der xdomea-Viewer auf mehreren Betriebssystemen Lauffähigkeit und in deutscher
Sprache verfügbar sein soll, reichen die in der standardmäßig gesetzten TargetPlattform installierten Eclipse-Plug-ins nicht aus. Daher müssen die im Ordner
{EXPORT_ADDONS} bereitgestellten Komponenten genutzt werden:
Öffnen Sie Ihre Installation der Eclipse-IDE und navigieren Sie über das Menü zu
[Window] [Preferences] [Plug-in Development] [Target Plattform]. Klicken Sie
hier auf den Button [Add] um einen neue Zielplattform hinzuzufügen.
Lassen Sie die Standard-Einstellungen bestehen und klicken Sie auf [Next >]. Geben
Sie einen sprechenden Namen (bspw. „Eclipse RCP 3.5.1 + Delta Pack + Language
Pack“) ein und fügen Sie die zuvor extrahierten Komponenten unterhalb von
{EXPORT_ADDONS} hinzu, in dem Sie ggf. mehrmals im Kartenreiter „Locations“ auf
[Add] klicken. Stellen Sie ggf. unter dem Kartenreiter „Environment“ die zu
verwendende JRE auf das zuvor installierte JDK 5.0. Dies ist nur nötig wenn das JDK
5.0 die einzige JVM auf ihrem Rechner ist. Klicken Sie auf [Finish].
Nun müssen Sie ihre neu angelegte Target-Plattform aktivieren. Dies erreichen Sie,
in dem Sie den Haken in der dazugehörige Checkbox setzen. Klicken Sie
abschließend auf [OK].
Ihre Entwicklungsumgebung ist damit vollständig eingerichtet.
In den folgenden Abschnitten werden die beiden importieren Eclipse-Projekte
eingehend beschrieben. Anweisungen zum Export der Anwendung erhalten Sie in
Abschnitt „3.5 Zusammenstellen der Gesamtanwendung“.
3.3
3.3.1
Weiterentwicklung des Viewer-Frameworks
technische Basis
Das Viewer-Framework wurde auf Basis von JAVA 5.0 implementiert. Die
Oberflächengestaltung setzt auf der Eclipse RCP auf. Zum Extrahieren der
relevanten Daten aus den xdomea-Nachrichten wird die Bibliothek Commons
Compress eingesetzt. Zur Validierung und Transformierung der in den xdomeaNachrichten enthaltenen XML-Dateien wird Saxon-HE eingesetzt. Log-Ausgaben
werden durch die Nutzung von Log4j realisiert.
3.3.2
Modularisierung
Die Gesamtheit der Quellcodes ist in zwei Eclipse-Projekte aufgeteilt:
zum einen in das Projekt xdomea-Viewer-core, das die Kernfunktionalitäten
(Extrahieren, Validieren, Transformieren) enthält. Zum anderem in das Projekt
xdomea-Viewer-gui, das die Quellcodes für die Darstellung als RCP-Anwendung
enthält. Auf diese Weise können XSL-Entwickler
4. Januar 2010
Seite 13/27
xdomea-Viewer
3.3.3
Beschreibung des Projekts: xdomea-Viewer-core
Das Viewer-Framework besteht in Anlehnung an die wesentlichen Funktionalitäten
aus folgenden Modulen:
•
•
•
•
•
Extrahierungsmodul: extrahiert die ZIP-Datei einer xdomea-Nachricht mit
Hilfe von Commons Compress in das Arbeitsverzeichnis
Validierungsmodul: prüft die xdomea-Nachricht auf Vollständigkeit und
formale Richtigkeit
Transformationsmodul: transformiert mit Hilfe von Saxon die XML-Datei
einer xdomea-Nachricht
Kopiermodul: kopiert ggf. benötigte Ressourcen an einen beliebigen
Speicherort
Visualisierungsmodul: fügt die zuvor genannten Module zur
Visualisierungsfunktionalität zusammen
Weiterhin existiert ein Konfigurationsservice, über den die Modulen die nötigen
Informationen abfragen können.
Implementierung
Die Implementierung der Anwendung erfolgt im Namensraum
de.xoev.xdomea.viewer. Im Folgenden werden die wichtigsten Ausschnitte der
Implementierung dargestellt. Tiefergehende Informationen erhalten Sie aus der
JavaDoc und dem kommentierten Quellcode.
xdomea-Viewer
4. Januar 2010
Seite 14/27
Konfigurationsservice
Das Paket de.xoev.xdomea.viewer.configuration enthält alle Klassen zur
Verarbeitung der Funktionalität der Anwendung. Die folgende Abbildung zeigt das
Klassendiagramm dieses Pakets.
Abbildung 4: Klassendiagramm Paket de.xoev.xdomea.viewer.configuration
Die Anwendung ist darauf ausgelegt mehrere Konfigurationen (eine für jede xdomeaVersion) zu unterstützen. Die Konfiguration wird nach dem Start der Anwendung von
der Utility-Klasse ConfigurationParser ausgelesen und in mehreren Instanzen der
Klassen Configuration und CopyInformationen im Hauptspeicher bereitgestellt. Über
die Singleton-Klasse ConfigurationService haben andere Programmteile die
Möglichkeit auf die Konfiguration zuzugreifen. Weiterhin ist es möglich geänderte
Konfigurationseinstellungen zu speichern. Das Auslesen und Speichern einer
Konfigurationsdatei ist mit XMLBeans umgesetzt.
4. Januar 2010
Seite 15/27
xdomea-Viewer
Konfigurationsmöglichkeiten
Um das Viewer-Framework möglichst Flexibel zu halten, sind folgende Parameter
konfigurierbar:
•
•
•
•
unterstützte xdomea-Versionen
die für die Validierung zu verwendenden XML-Schemata zu jeder Version
die für die Transformierung zu verwendenden XSL-Templates für
verschiedene Validierungsvarianten zu jeder Version
die für die Visualisierung benötigten Ressourcen zu jeder Version
Zur Speicherung der Konfiguration wird eine XML-Datei verwendet, die einem zuvor
entwickelten Schema folgt. Im Folgenden ist ein Beispiel der Konfigurationsdatei zu
sehen:
<?xml version="1.0" encoding="UTF-8"?>
<xdomeaViewer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="configuration.xsd">
<configuration>
<xdomeaVersion versionsNr="V2.1.0">
<schemas>./xsd</schemas>
<visualisation>
<variant id="htmlVariante" name="HTML">
<template>./xslt/main.xsl</template>
<copyIntructions>
<basepath>./xslt</basepath>
<includes>[img|css|js]/*</includes>
<excludes>Kopie*</excludes>
</copyIntructions>
</variant>
</visualisation>
</xdomeaVersion>
<xdomeaVersion versionsNr="V2.0.1">
...
</xdomeaVersion>
</configuration>
</xdomeaViewer>
Die folgende Abbildung zeigt das zur XML-Datei passende Schema:
xdomea-Viewer
Abbildung 5: Schema der Konfigurationsdatei
4. Januar 2010
Seite 16/27
xdomea-Viewer
4. Januar 2010
Seite 17/27
Visualisierung
Die Kernfunktionalität der Anwendung wurde in mehrere in sich geschlossene Module
aufgeteilt. Diese Module sind unterhalb des Pakets de.xoev.xdomea.viewer.modules
angesiedelt. Das ValidationModule ist hierbei eine Ausnahme (siehe folgende
Abschnitt). Die folgende Abbildung zeigt das Klassendiagramm des Pakets.
Abbildung 6: Klassendiagramm Paket de.xoev.xdomea.viewer.modules
xdomea-Viewer
4. Januar 2010
Seite 18/27
Alle Module implementieren die Schnittstelle Module. Dieses erzwingt das
Vorhandensein der Methoden setInput und process. Mit setInput wird die zu
verarbeitende Ressource gesetzt, während process die Modul-spezifische
Verarbeitung vornimmt. Zur Vereinfachung ist in der abstrakten Klasse
AbstractModule die Methode setInput bereits implementiert. Alle konkreten
Ausprägungen der Schnittstelle Module beerben die Klasse AbstractModule und
müssen daher lediglich die Methode process implementieren.
Validierung
Da die Validierung einer xdomea-Nachricht verhältnismäßig komplex ist, wurden die
dafür nötigen Klassen in einem gesonderten Paket unterhalb von
de.xoev.xdomea.viewer.modules zusammengefasst. Die folgende Abbildung zeigt
das Paket de.xoev.xdomea.viewer.modules.validation.
Abbildung 7: Klassendiagramm Paket
de.xoev.xdomea.viewer.modules.validation
4. Januar 2010
Seite 19/27
xdomea-Viewer
Die Validierungsfunktionalität der Anwendung wurde in mehrere Validator-Klassen
aufgeteilt. Diese Klassen implementieren die Schnittstelle Validator. Dieser erzwingt
das Vorhandensein der Methode validate. Ein Teil der Validator-Klassen überprüfen
das Verzeichnis in das die xdomea-Nachricht extrahiert wurde. Diese Klassen
(FilenamesValidator und DirectoryStructureValidator) beerben die abstrakte Klasse
DirectoryValidator, die die get- und set-Methoden zum Setzen des zu überprüfenden
Verzeichnisses implementiert. Die die übrigen Validator-Klassen implementieren die
Schnittstelle Validator direkt. Das ValidationModule fügt die einzelnen ValidatorKlassen zur gesamten Validierungsfunktionalität der Anwendung zusammen.
3.3.4
Beschreibung des Projekts: xdomea-Viewer-gui
Die Anwendungsoberfläche ist mit Eclipse RCP umgesetzt und baut auf dem Konzept
zur Verwendung von Perspektiven, Ansichten und Editoren auf. Eine Beschreibung
dieses Konzepts würde den Rahmen dieser technischen Konzeption sprengen. Daher
sei an dieser Stelle auf die im Internet zu findende umfangreiche Dokumentation der
1
Eclipse RCP verwiesen.
Im Folgenden werden lediglich die an der RCP-Oberfläche durchgeführten
Anpassungen beschrieben. Detaillierte Informationen erhalten Sie in der JavaDoc
und im kommentierten Quellcode der Anwendung.
Import-Assistent
Der Nutzer wird beim Visualisieren einer xdomea-Nachricht durch einen ImportAssistenten unterstützt. Der Quellcode für den Import-Assistenten befindet sich im
Paket de.xoev.xdomea.viewer.gui.wizards. Innerhalb dieses Pakets existieren die
beiden Klassen ImportMessageWizard und ImportMessageWizardPage. Die Klasse
ImportMessageWizard enthält die Funktionalitäten zum Durchführen der nötigen
Verarbeitung zum visualisieren der xdomea-Nachricht. Die Klasse
ImportMessageWizardPage erzeugt die Eingabe-Elemente im zweiten Schritt des
Import-Assistenten.
1
http://wiki.eclipse.org/Rich_Client_Platform (Eclipse Wiki) und
http://www.vogella.de/articles/RichClientPlatform/article.html (Tutorial)
4. Januar 2010
Seite 20/27
xdomea-Viewer
Arbeitsbereich-Wechseln Dialog
Die RCP-Anwendung kommt nicht ohne einen Arbeitsbereich aus, in dem die Daten
der Anwendung gespeichert werden können. Im Paket
de.xoev.xdomea.viewer.gui.dialogs befindet sich hierzu die Klasse
PickWorkspaceDialog. Diese Klasse erzeugt alle Eingabe-Elemente des Dialogs zum
Wechseln oder Bestimmen des Arbeitsbereichs. Weiterhin übernimmt sie die Prüfung
und Speicherung der Nutzereingaben.
Im Paket de.xoev.xdomea.viewer.gui.actions befindet sich die Action-Klasse
SwitchWorkspaceAction. Diese Klasse stellt eine gesonderte Möglichkeit dar, den
PickWorkspaceDialog aufzurufen und wird benötigt, um der Anwendung den Shortcut
zu dessen Aufruf mitzuteilen.
Weiterhin befindet sich in dem Paket de.xoev.xdomea.viewer.gui.commands die
Handler-Klasse SwitchWorkspaceHandler. Diese Klasse existiert um den
PickWorkspaceDialog auch über das Menü der Anwendung bereitstellen zu können.
Konfigurationsseite „xdomea-Viewer“
Die Einstellungen zum xdomea-Viewer lassen sich mit einer gesonderten
Konfigurationsseite setzen. Im Paket de.xoev.xdomea.viewer.gui.preferences existiert
hierzu die Klasse XdomeaViewerPrefrerencePage. Diese Klasse erzeugt alle
Eingabe-Elemente der Konfigurationsseite zur Pflege der xdomea-Versionen, für die
die Anwendung konfiguriert ist. Weiterhin übernimmt sie die Prüfung und Speicherung
der damit in Verbindung stehenden Nutzereingaben. Die Eventlistener für die Buttons
zum Hinzufügen, Bearbeiten und Löschen von Konfigurationen für xdomea-Versionen
befinden sich im untergeordneten Paket
de.xoev.xdomea.viewer.gui.preferences.listeners.
Im Paket de.xoev.xdomea.viewer.gui.preferences befindet sich weiterhin die Klasse
EditConfigurationDialog. In diese Klasse sind alle Eingabe-Elemente des Dialogs zur
Einstellung der Konfiguration für eine bestimmte xdomea-Version ausgelagert.
Außerdem enthält sie Funktionen zur Prüfung und Speicherung der damit in
Verbindung stehenden Nutzereingaben.
Häufig mit Textfeldern in Verbindung stehende Funktionalitäten wie das setzen von
Labels und das Validieren der Nutzereingabe wurde in das Paket
de.xoev.xdomea.viewer.gui.util.forms ausgelagert.
3.3.5
Erweiterungsmöglichkeiten
Bei Erweiterungen kann auf bestehende Module zurückgegriffen werden.
Insbesondere die Nutzung der fertigen Module UnzipModule und ValidationModule ist
hierbei zu empfehlen, da so eine solide und gleichmäßige Ausgangsbasis für die
weitere Verarbeitung der xdomea-Nachrichten geschaffen wird. Die Erweiterungen
zum xdomea-Viewer sind gesondert in weiteren Modulen zu implementieren.
Zusätzliche Konfigurationseinstellungen sind – der bestehenden Implementierung
folgend – in der im in vorhergehenden Abschnitt vorgestellten Konfigurationsdatei zu
hinterlegen. Hierzu ist das Schema zu erweitern und die Implementierung der mit der
4. Januar 2010
Seite 21/27
xdomea-Viewer
Konfiguration verbundenen Klassen anzupassen. Um die neuen Funktionalitäten über
die Benutzeroberfläche verfügbar zu machen, können die Funktionen der Eclipse
RCP genutzt werden.
3.4
Weiterentwicklung der XSL-Templates
Zur Darstellung der Informationen einer xdomea-Nachricht werden XSL-Templates
eingesetzt. Diese Templates transformieren die XML-Datei einer xdomea-Nachricht in
eine HTML-Datei. Die Templates befinden sich innerhalb des xdomea-Viewer-core
Projekts unterhalb des Verzeichnisses resources/{XDOMEA_VERSION}/xslt. In
diesem Verzeichnis liegen ebenfalls alle für die Visualisierung nötigen Dateien (CSS-,
JPG- und JS-Dateien).
Die XSL-Templates bestehen aus einem Haupt-Template und mehreren modular
aufgebauten Sub-Templates. In den Sub-Templates wurden die
Transformationsregeln zur Darstellung bestimmter Teile der XML-Datei einer
xdomea-Nachricht sinnvoll zusammengefasst. Die folgende Abbildung zeigt die
logische Aufteilung der HTML-Darstellung einer xdomea-Nachricht.
Logo
Nachrichten-Daten
Tab-Navigation
Haupt-Navigation
Inhaltsbereich
Abbildung 8: logische Aufteilung der HTML-Darstellung einer xdomeaNachricht
Die folgende Tabelle listet die momentan wichtigsten Sub-Templates auf und
beschreibt sie in aller Kürze:
Template
contentContainer.xsl
documentation.xsl
elementTranslator.xsl
Beschreibung
Erstellt den Inhaltsbereich
gibt den Hinweis-Text in den NachrichtDaten aus (in Abhängigkeit zur
transformierten Nachricht)
Erzeugt die sprechenden Namen für die
4. Januar 2010
Seite 22/27
xdomea-Viewer
helper.xsl
innerContent.xsl
leftNavigation.xsl
topNavigation.xsl
Navigationspunkte der Haupt- und TabNavigation und Eigenschaftsnamen im
Inhaltsbereich
Enthält Utility-Funktionen
erstellt die Elemente im Inhaltsbereich
der Seite
Erstellt die Haupt-Navigation
Erstellt die Tab-Navigation
Jedes Sub-Template transformiert die Inhalte eines XML-Fragments in ein HTMLFragment. Das Haupt-Template setzt diese HTML-Fragmente schließlich zu einer
kompletten HTML-Seite zusammen.
Durch die Aufteilung in ein Haupt- und mehrere Sub-Templates wird eine flexible
Erweiterung um und Wiederverwendung von Nachrichtentypen und
Basiskomponenten möglich.
3.4.1
CSS-Konventionen
Um eine vernünftige Strukturierung und Funktionalität der Anwendung zu
gewährleisten, orientieren sich die Namen der CSS-Klassen an den folgenden
Konventionen:
•
•
•
•
•
Vorkommen von '.' wird durch ein '-' ersetzt
Die CSS-Klassen von Komponenten lauten wie ihre Element-Repräsentation
in XML
Bei Komponenten wird das u. a. Attribut class mit dem Namen der ElementRepräsentation in XML gefüllt.
Beispiel: Komponente 'kontakt':
<div class="kontakt">...</div>
Bei Nachrichten wird das Attribut id mit dem Namen der ElementRepräsentation in XML gefüllt.
Beispiel: Nachricht ‚nachrichtengruppe.nachricht.123‘:
<div id="nachrichtengruppe-nachricht-123">...</div>
CSS-Klassen, die spezifisch für den xdomea-Viewer sind, wird ein 'xdv-'
vorangestellt um sie von CSS-Klassen, die sich aus dem Namen der
Element-Repräsentation einer Komponente ergeben, unterscheiden zu
können.
Beispiel: Nachricht ‚kontakt‘:
<div class="kontakt xdv-hidden">...</div>
4. Januar 2010
Seite 23/27
xdomea-Viewer
3.4.2
Einsatz von JavaScript
Grundsätzlich müssen die Transformationsergebnisse des xdomea-Viewers
barrierefrei sein. Daher wird JavaScript lediglich zur Steigerung der
Benutzerfreundlichkeit der Anwendung eingesetzt.
In der barrierefreien Version der Anwendung werden die Inhalte nacheinander heraus
gerendert. Die Navigation zwischen den zahlreichen Informationen erfolgt mit
Inhaltsverzeichnissen und Sprungmarken. Die folgende Abbildung zeigt exemplarisch
die barierrefreie Darstellung einer xdomea-Nachricht.
Abbildung 9: barrierefreie Darstellung einer xdomea-Nachricht
Die benutzerfreundliche Version der Darstellung basiert auf dem gezielten Aus- und
Einblenden von Information, sodass beim Benutzer der Eindruck entsteht er navigiere
durch eine Anwendung. Dies wird mit JavaScript und entsprechenden CSSDefinitionen erreicht. Sollte der Benutzer kein JavaScript aktiviert haben, dann
werden alle Informationen untereinander ausgegeben.
Wie bei der barrierefreien Darstellung einer xdomea-Nachricht werden die Inhalte
nacheinander heraus gerendert. Am Ende des HTML-Dokuments werden per
JavaScript-Injection Funktionen zum Ein- und Ausblenden von HTML-Fragmenten auf
die Eventlistener bestimmter Elemente gelegt. Hierzu komm jQuery
(http://jquery.com/) in der Version 1.3.2 zum Einsatz.
Um die für die Ein- und Ausblendenfunktionalität relevanten HTML-Fragmente
erkennen zu können, werden bestimmte CSS-Klassen auf bestimmte HTMLElemente vergeben. Die Navigation in der Anwendung erfolgt über die
Hauptnavigation auf der linken Seite und über die Tab-Navigation im oberen Bereich
des Inhalts.
4. Januar 2010
Seite 24/27
xdomea-Viewer
Für jeden Eintrag dieser beiden Navigationen werden drei CSS-Klassen auf
verschiedene HTML-Elemente benötigt um das Ein- und Ausblenden umzusetzen. Im
Falle der Hauptnavigation sind das folgende CSS-Klassen:
CSS-Klasse
xdv-linkSource
xdv-linkTarget
xdv-target[lfdNr]
Beschreibung
CSS-Klasse, die auf HTML-Elemente vergeben wird,
die einen Link zu einem bestimmten Inhalt darstellen
(Link-Quelle)
CSS-Klasse, die auf HTML-Elemente vergeben wird,
die einen Inhalt zu einem bestimmten Link darstellen
(Link-Ziel)
CSS-Klasse, die die Verknüpfung zwischen Link-Quelle
und Link-Quelle herstellt. Hierzu dient ein Zähler (hier
als [lfdNr] dargestellt).
Die CSS-Klassen werden auf bestimmte HTML-Elemente nach dem folgenden
Muster angewendet:
<a class="xdv-linkSource" href="#1234">allgemeine
Nachrichteninformationen</a>
[...]
<div class="... xdv-linkTarget xdv-target1234">
<a name="1234">allgemeine Nachrichteninformationen</a>
[...]
</div>
[...]
Das <a>-Tag erhält die CSS-Klasse xdv-linkSource und eine eindeutige Zahl im
Attribut href (dient gleichzeitig als Sprungmarke). Das zu verlinkende <div>-Tag erhält
die beiden CSS-Klassen xdv-linkTarget und xdv-target[lfdNr]. Die Zahlen im hrefAttribut und in der CSS-Klasse xdv-target[lfdNr] sind hierbei identisch, sodass eine
Verknüpfung zwischen den beiden HTML-Elementen erfolgen kann. Die folgenden
JavaScript-Anweisungen implementieren mit Hilfe von jQuery die Ein- und
Ausblendenfunktionalität:
<script language="javascript" ...>
// linke navigation
$("a.xdv-linkSource").click(function (event) {
event.preventDefault();
$("div.xdv-linkTarget").hide("slow");
var lfdNr = this['href'].split("#")[1];
$(" div.xdv-target" + lfdNr).show("slow");
4. Januar 2010
Seite 25/27
xdomea-Viewer
});
</script>
Alle <a>-Elemente mit der Klasse xdv-linkSource blenden nach einem Mausklick alle
<div>-Elemente mit der Klasse xdv-linkTarget aus und das <div>-Element, der die
CSS-Klasse xdv-target[lfdNr] zugewiesen ist, wieder ein. Die Implementierung ist
analog für die Tab-Navigation.
3.5
Zusammenstellen der Gesamtanwendung
Für die Zusammenstellung wird die Nutzung von Maven 2 und der bereits
vorkonfigurierten Project-Object-Model Dateien empfohlen. Wenn Sie das M2Eclipse
Plugin in ihrer Entwicklungsumgebung installiert haben, dann können Sie mit einem
Rechtsklick auf diese Datei und einer Auswahl von [Run as] -> [Maven install] das
jeweilige Maven Artefakt (Java-Bibliothek, Verzeichnis, …) automatisch erstellen
lassen. Alternativ können Sie auch in einer Konsole in einem Verzeichnis auf Höhe
der jeweiligen pom.xml den Befehl mvn install ausführen.
Aus Abschnitt “3.3.2 Modularisierung“ geht hervor, dass die Quellcodes in zwei
Eclipse-Projekte aufgeteilt sind. Daher sind bei der Zusammenstellung der
Anwendung mehrere Schritte nötig. Nachfolgend sind die diese Schritte aufgeführt.
Der Übersichtlichkeit halber werden bei Pfadangaben fortan für die
Wurzelverzeichnisse der Eclipse-Projekte folgende Abkürzungen benutzt:
xdomea-Viewer-core: {CORE}
xdomea-Viewer-gui: {GUI}
3.5.1
Änderungen am dem XML-Schema der Konfigurationsdatei
Sofern am XML-Schema der Konfigurationsdatei Änderungen erfolgt sind, muss es
mit XMLBeans in eine Java-Bibliothek übersetzt werden. Nutzen Sie hierzu die Datei
{CORE}/conf/pom.xml. Nach der Ausführung von Maven sollte ein neues oder
aktualisiertes Maven Artefakt unter {CORE}/conf/target/xdomea-viewer-configtypes[Versionsnummer].jar bereitstehen.
3.5.2
Änderungen am Quellcode des Projekts xdomea-Viewer-core
Sofern an den Quellcodes des Projektes xdomea-Viewer-core Änderungen erfolgt
sind, müssen diese Änderungen ebenfalls zu einer Java-Bibliothek zusammengebaut
werden. Nutzen Sie hierzu die Datei {CORE}/pom.xml. Nach der Ausführung von
Maven sollte ein neues oder aktualisiertes Maven Artefakt unter
{CORE}/target/xdomea-viewer-core-[Versionsnummer].jar bereitstehen.
4. Januar 2010
Seite 26/27
xdomea-Viewer
3.5.3
Änderungen an den XSL-Templates
Sofern Änderungen an den XSL-Templates erfolgt sind, müssen Sie lediglich bei der
Zusammenstellung die Hinweise zur Änderung an der Oberfläche beachten (siehe
nächster Abschnitt).
3.5.4
Änderungen an der Oberfläche (Eclipse-RCP)
Führen Sie ggf. alle zuvor genannten Anweisungen aus und kopieren Sie die neu
erstellten Maven Artefakte wie folgt in das xdomea-Viewer-gui Projekt (dieser Schritt
ist nur nötigt, sofern Sie an den o. g. Resources Änderungen vorgenommen haben):
1.) von {CORE}/conf/target/xdomea-viewer-configtypes-1.0.0.jar nach
{GUI}/lib/xdomea-viewer-configtypes-1.0.0.jar
2.) von {CORE}/target/xdomea-viewer-core-1.0.1.jar nach {GUI}/lib/xdomeaviewer-core-1.0.1.jar
Vergewissern Sie sich, dass ihre Entwicklungsumgebung keine
Kompilierungsfehler anzeigt!
Öffnen Sie nun die Datei {GUI}/viewer.product. Starten Sie den Export Mechanismus
der Eclipse-IDE um die Anwendung in ein beliebiges Verzeichnis zu exportieren
(bspw. /exports/xdomea-Viewer)
Fügen Sie abschließend die aktuellen Schema-Dateien und XSL-Templates zur
exportierten Anwendung hinzu. Kopieren Sie hierzu den Ordner {CORE}/resources in
das Wurzelverzeichnis der exportierten Anwendung (bspw. nach /exports/xdomeaViewer/resources).
Die Zusammenstellung der Anwendung ist damit abgeschlossen. Sie kann nun
gestartet und in vollem Umfang genutzt werden.
xdomea-Viewer
4
4. Januar 2010
Seite 27/27
Lizensierung
Der xdomea-Viewer und die Umsetzung zur Darstellung der xdomea-Nachrichten
bauen auf folgende Software auf:
Eclipse RCP 3.5 (Eclipse Public License 1.0)
Log4J (Apache Software License 2.0)
Commons Compressions (Apache Software License 2.0)
Commons CLI (Apache Software License 2.0)
XMLBeans 2.3.0 (Apache Software License 2.0)
Saxon-HE 9.2 (Mozilla Public License 1.1)
Mockito 1.8.2(Massachusetts Institute of Technology License)
jOuery 1.3.2 (Massachusetts Institute of Technology License)
Die Lizensierung der o. g. Softwarebestandteile bleibt bestehen. Alle in diesem
Dokument beschriebenen und die restlichen zum xdomea-Viewer gehörenden
Quellcodes und sonstigen Dateien sind unter der EUPL
(http://ec.europa.eu/idabc/eupl) lizensiert.