Anleitungen

Inhaltsverzeichnis

 

Die hier aufgeführten Anleitungen umfassen auch Teile, die nicht Kern der XUBetrieb- und XUKommunalabwasser-Pflegeaufgaben sind, um den Einstieg in die XÖV-konforme Modellierung von Standards zu ermöglichen.

Da ein Handbuch für die Nutzung der XÖV-Produktionsumgebung nicht vorliegt, sind Anleitungen, die sich ausschließlich mit der Nutzung der XUBetrieb-Modellkomponenten befassen, für die Entwicklung neuer XÖV-konformer Standards unter Nutzung von XUBetrieb praktisch nicht zielführend.

Folgende Anleitungen stehen für die Nutzung der KoSIT XÖV-Werkzeuge und von XUBetrieb zur Verfügung:

  • XÖV-Umgebung einrichten
  • Bearbeitung UML2, XGenerator, DocBook2PDF
  • DocBook: Initiale Anpassungen Starterpaket auf Echtpaket
  • XUBetrieb-Modulnutzung

 

 

XÖV Umgebung einrichten

Alle hier aufgeführten Operationen sind auch mit XGenerator 2.6.1 und Profil V1.4 notwendig. Sobald ENDA Kenntnis erlangt, wie welche neueren Pakete miteinander harmonieren, wird diese Seite aktualisiert.
Zur Jahreswende 2015/2016 waren XGenerator 2.5.1, Profil V1.3 und Starterpaket 1.0.1 die aktuellste Werkzeugkombination, die mit Hilfe der KoSIT dazu gebracht werden konnte, miteinander zu harmonieren.

Ordner und Unterordner vorbereiten

•    Ordner (O) anlegen (Basisordner, O ist hier Platzhalter für einen aussagekräftigen Namen)
•    O/model : UML2-Modell (MagicDraw)
•    O/model_export : Der Export als Eclipse V2.x XMI File für die Verwendung mit XGenerator
•    O/XGenProject : Sammelordner für XGenerator-Lauf.
•    O/XGenProject/model : Hier wird vor XGenerator-Lauf der Inhalt des model_export hineinkopiert

Basisfüllung der Ordnerstruktur

•    Hier referenzierte Pakete liegen unter KoSIT Downloads
•    "XOEV-Starterpaket 1.0.1 - MD18.zip" in O/XGenProject entpacken
•    Ordner "O/Profil.Rev.1.3" anlegen
•    "XOEV-Profil 1.zip" in "XOEV-Profil_1.3.zip" umbenennen
•    "XOEV-Profil_1.3.zip" in Ordner "O/Profil.Rev.1.3" entpacken
•    Datumsmäßig ältere Profil-Dateien ("./model", "./templates") über die Dateien in "O/XGenProject" mit dem Starterpaket kopieren (altes Profil sticht neues Starterpaket)
•    "O/XGenProject/documentation" (falls vorhanden löschen und durch) Symlink auf "O/XGenProject/src"-Verzeichnis (er)setzen
•    Sicherung XGenProject.clean.tbz des so erzeugten XGenProject-Ordners erstellen

Fehlerkorrekturen

•    Problem mit "O/XGenProject/model/osci-docbook.operations".
   •    "osci-docbook.operations" in "osci-docbook.operations.ori" umbenennen
•    Problem mit "O/XGenProject/documentation/spezifikation.xml": Die Schemadatei "http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" konnte nicht gefunden werden
   •    Eine solche gibt es nicht (mehr?). Richtig ist: "http://docbook.org/xml/5.0/rng/docbookxi.rng"
•    "O/XGenProject/src/basisdatentypen/basisdatentypen.xml": include-Anweisung zeigt fälschlich auf "../../build/docBook/dokumente/XOEV_Starterpaket/Basisdatentypen/Beispielbasisdatentyp.xml".
Korrekt ist "../../build/docBook/dokumente/xoev-starterpaket-datentypen/Beispielbasisdatentyp.xml"
•    "O/XGenProject/src/informationsmodell/beispielthemenkomplex.xml": include-Anweisung zeit fälschlich auf "../../build/docBook/dokumente/XOEV_Starterpaket/Baukasten/Beispielbaustein.xml".
Korrekt ist "../../build/docBook/dokumente/xoev-starterpaket-baukasten/Beispielbaustein.xml"
•    "O/XGenProject/src/informationsmodell/codesUndCodelisten.xml" zeigt fälschlich auf "../../build/docBook/dokumente/anhang/codes/codelistenIndex.xml".
Derzeit keine Lösung außer auskommentieren.
•    "O/XGenProject/src/informationsmodell/codesUndCodelisten.xml" zeigt fälschlich auf "../../build/docBook/dokumente/anhang/codes/code.beispiel.xml".
Richtig wäre "../../build/docBook/dokumente/xoev-starterpaket-baukasten/Code.Beispiel.xml"

 

Bearbeitung UML2, XGenerator, DocBook2PDF

Der hier abgebildete Arbeitsablauf hat sich bei der Bearbeitung von XUBetrieb und XUKommunalabwasser etabliert:

•    O/model/XUBetrieb-Modul.mdxml mit MagicDraw V18 (kurz: MD) öffnen, bearbeiten, speichern (nur notwendig, wenn Änderungen am XUBetrieb-Modul notwendig sind)
•    Sofern das zu bearbeitende Modell bereits in MD geöffnet ist,
   •    dort auf "XUBetrieb «xsdModel» [XUBetrieb-Modul.mdxml]" Kontextmenü - Modules - Reload Module
        Mit diesem Schritt werden die Änderungen am XUBetrieb-Modul in dem das Modul nutzenden UML2-Projekt bekannt gemacht
   •    speichern
•    XUBetrieb (TOP) markieren, Menu File - Export to - "Eclipse UML2 (v2.x) XMI File"
   •    in O/model_export exportieren
        Damit werden die UML2-Modellinformationen in einem Austauschformat (XMI) gespeichert, um mit dem XGenerator verarbeitet werden zu können
•    Copy O/model_export/* nach O/XGenProject/model
•    XGenerator starten
   •    Falls noch nicht vorhanden: Projekt erzeugen: Project - Manage - Create
   •    Project Directory: Ordner O/XGenProject wählen
   •    Model: z. B. XUKommunalabwasesr.uml
   •    Finish; OK
   •    Clean
   •    Refresh
•    (Bei XUBetrieb muss eine Warnung (kein Fehler!) kommen, da dieses als Bibliothek keinen UseCase umfasst)
   •    Fehlerbehandlungen
      •    Task 'xsd': XSD: Type reference 'http://www.xubetrieb.de/schema/xubetrieb/1_2_1#<Irgendetwas>' is unresolved
      •    Warning Task 'xsd': XSD: The location 'http://www.xubetrieb.de/schema/xubetrieb/1_2_1/xubetrieb-basisdatentypen...' has not been resolved
      •    Prüfen, ob unter http://www.xubetrieb.de/schema/xubetrieb/1_2_1 (oder entsprechende Version) die Schemata zur Verfügung stehen! Ggf. stimmt die Versionsnummer nicht oder Schemata verweisen auf andere Schemata mit abweichender, nicht online verfügbarer Versionsnummer.
Alle abgeleiteten Standards sind für diesen Fehler anfällig.
Lösung: Im Paket, das die nicht online stehende Komponente nutzt, den Tag Value "deployment" des Stereotyps «xsdModel» von true auf false setzen
•    XGenerator schließen
     Sind beim Arbeitsschritt drei, DocBook, des XGenerators keine schwerwiegenden Fehler aufgetreten, so kann versucht werden, eine PDF-Spezifikation zu erstellen. Hier wurde dafür das Werkzeug oXygen eingesetzt:
•    cd O/XGenProject/src
•    oxygen spezifikation.xml
•    DocBook -> PDF Transformation auf spezifikation.xml
   •    Ergebnis: O/XGenProject/src/out/spezifikation.pdf oder Fehler.
   •    Korrekturen am besten mit oXygen auf spezifikation.xml und den davon importierten Dateien ausführen. Falls Dateien nicht gefunden werden, oXygen auf der Konsole aus dem ''O/XGenProject''-Verzeichnis starten. Evtl. stimmen dann die relativen Pfade.
   •    Docbook initiale Anpassungen Starterpaket auf Echtpaket
•    Ggf. bis zum DocBook-Schritt iterieren. Das PDF ist der beste Startpunkt für die Qualitätssicherung.

 

DocBook einrichten

DocBook: Initiale Anpassungen Starterpaket auf Echtpaket

Händische Korrekturen

auf folgenden xml-Dateien des DocBook-Source (<O/XGenProject> = ${O}):

•    ${O}/src/basisdatentypen/basisdatentypen.xml: XOEV_Starterpaket durch dem im UML2-Modell festgelegten Modellpaketnamen ersetzen
•    ${O}/src/informationsmodell/beispielthemenkomplex.xml: XOEV_Starterpaket wie oben ersetzen
•    ${O}/src/beispielnachrichtengruppe/nachrichten.xml: analoges Vorgehen, jedoch sind hier zwei falsche Pfadangaben zu korrigieren
•    Weitere Pfadanpassungen könnten folgende Datei betreffen:
   •    ${O}/src/informationsmodell/komponenten.xml
•    Änderungen an den Dateien ${O}/build/docBook/* sollten unterlassen werden, da diese bei jedem XGenerator-Durchlauf neu erstellt werden.
Es empfiehlt sich ein Reverse-Engineering der Dateien unterhalb der Ordner O/XGenProject/[src|docbookzubehoer|templates]. Bei Validierungsproblemen sollte immer von O/XGenProject/src/spezifikation.xml ausgegangen werden.

#s im PDF-Dokument

Wenn im erstellten PDF-Dokument an zahlreichen Stellen der textuelle Inhalt ausschließlich durch Hashmarks (#) repräsentiert wird, so ist in der DocBook-Produktionskette für das XSLT mindestens ein unbekannter Font eingestellt.
Das Transformation Szenario im oXygen ist dann zu editieren und die beiden font-Parameter (Knopf "Parameters ()") z. B. auf 'Calibri, DejaVu Sans' zu stellen.

Stylesheet einstellen

Das DocBook-Stylesheet O/XGenProject/docbookzubehoer/stylesheets/kosit/kosit_docbook.xsl sollte für den eigenen Bedarf angepasst und im DocBook Transformation Scenario unbedingt angegeben werden, um funktionierende Referenzen in den Tabellen des PDF-Spezifikationsdokuments zu erhalten.

 

 

XUBetrieb-Modulnutzung

Das MagicDraw UML2-Modul "XUBetrieb-Modul" wird als Modul in das Paket „Data::Externe Modelle“ eingehängt.

 

GRAFIK??

 

Damit stehen als wesentliche Bausteine die UML-Klassen mit den fachlichen Objekten von Abfallverbringung bis Zeitraum und die Codelisten von Code.Abwasserbehandlungsart bis Code.Zehrstoff aus XUBetrieb zur Verfügung.

In der folgenden Abbildung sind zwei Entitäten „Abwasserbehandlung.Klaeranalge“ und „Abwasserbehandlung.IAS“ (IAS: Individulelle AbwasserSysteme) aus der XUBetrieb-Modellkomponente „Abwasserbehandlung“ abgeleitet worden. Dabei kam für die Modellierung der Beziehung das UML-Element „Generalization“ zum Einsatz, das mit den Stereotyp «xsdRestriction» versehen wurde.\

Dadurch werden die abgeleiteten Entitäten in den per XGenerator erstellten XML-Schemata über das entsprechende XML-Schema-Konstrukt „xsdRestriction“ aus der XUBetrieb-Entität gebildet.

GRAFIK?? Abb. Nutzung von XUBetrieb-Modellkomponente „Abwasserbehandlung“ für zwei neue Entitäten im Zielprojekt

 

Bei der Nutzung der Ableitung per Generalization «xsdRestriction» müssen folgende Randbedingungen beachtet werden:

•    Alle Kardinalitäten dürfen nur weiter eingeschränkt werden
•    Attribute mit einer Kardinalität von 1 oder mehr dürfen nicht entfallen (implizit)
•    Alle Typen dürfen nur die Orignaltypen sein oder eine Einschränkung der Originaltypen
•    Es dürfen keine Attribute hinzu kommen
•    Es darf auch das Attribut im derived type nicht nillable sein, wenn das Attribut im base type nicht nillable ist oder nicht existiert. Das ist bei XÖV jeweils im tag value «xsdElement»nillable abgelegt.
•    Die Reihenfolge der Attribute über «xsdElement»position muss exakt übereinstimmen.
     Achtung: Die Parserfehlermeldungen sind irreführend, wenn die Reihenfolge nicht eingehalten wird. Das betrifft Meldungen der Art "Element X ist im derived type erlaubt aber im base type nicht". Diese sind sehr wohl erlaubt, aber nicht an der entsprechenden Stelle.
•    Es sollten zur Validierung sowohl die Parser Xerxes als auch Saxon eingesetzt werden, da bei unterschiedlichen Fehlerbedingungen die Qualität der Fehlermeldungen der Parser unterschiedlich ist!

Fehler und Lösungen Baukasten-Klassen

NDR-28: Valide W3C-XML-Schemata

•    The attribute grundwasserkoerper of class Data.XUKommunalabwasser.Baukasten.WRRL.0001 violates the constraint 'Property.ElementAndAttributeTypesMustBeVisible'.
•    Für UML-Klasseneigenschaften verwendete «xsdNamedType»-Typen müssen in diesem «xsdSchema»-UML-Paket mit «xsdInclude» oder «xsdImport» sichtbar sein.
•    Lösung: Es muss eine Beziehung geben, mit der das bemängelte Paket die verwendeten Datentypen in das XML-Schema einbindet. Üblicherweise ist das per «xsdImport» oder -- wenn es der selbe Namespace ist -- per «xsdInclude».
     Das macht man dann in der Modellübersicht, in dem man eine Dependency vom Paket auf das vererbende Paket zieht und ihr danach den entsprechenden Stereotyp zuweist.
     Beispiel: XUK::Berichtspflichten auf XUB::Baukasten    

NDR-23: Umgang mit Restriktionen über unterschiedliche Namensräume

•    The generalization between Abwasserbehandlung and Abwasserbehandlung.0002 violates the constraint 'Generalization.TransNamespaceRestrictionImpliesUnqualifiedElements'.
•    Bei Restriktionen über mehrere Namensräume müssen die UML-Klasseneigenschaften mit «xsdElement» für die Eigenschaft "form" den Wert "unqualified" aufweisen.
•    Lösung: Im Modell des Generalization-Teils (meist eine XUBetrieb-Modellklasse) sind für die Attribute, die den «xsdElement»-Stereotyp tragen, der aus dem Stereotyp stammende Tag-Value "form" auf unqulified zu setzen. Ob das auf beiden Seiten passieren muss, ist unklar. Jedenfalls reicht es nicht, das nur auf der Seite der die Generalization nutzenden Klasse zu machen.

Fehler und Lösungen Listen

•    Alle Listen (Code.X) per Generalization «xsdRestriction» von Code abgeleiten
•    In allen Listen
   •    «xsdCode» tag listAgencyName der Klasse Code.X füllen
   •    «xsdCode» tag listName der Klasse Code.X füllen
   •    Herstellung eines sauberen code-Attributs:
      •    das content-Attribut in code umbenennen
      •    das code-Attribut bzw. konkret – dessen Typ – mit der korrespondierenden Enumeration «xsdCodeList» verbinden
      •    Das Attribut code bzw. – konkret dessen aus «xsdElement» stammendes Tag form – von qualified auf unqualified setzen
•    Herstellung eines sauberen listURI-Attributs:
   •    listURI Attribut der Codeliste hinzufügen
   •    listURI Attribut mit Stereotyp «xsdAttribute» versehen
   •    listURI mit Typ anyURI versehen
   •    default value des listURI Attributs mit Typ Literal String versehen
   •    default value des listURI Attributs mit einer URI befüllen
   •    listURI multiplicity auf 0..1 setzen
   •    listURI "is read only" auf true setzen
•    Herstellung eines sauberen listVersionID Attributs:
   •    listVersionID Attribut wird der Codeliste hinzugefügt
   •    listVersionID Attribut mit Stereotyp «xsdAttribute» versehen
   •    listVersionID wird mit Typ normalizedString versehen
   •    default value des listVersionID Attributs wird mit Typ Literal String versehen
   •    default value des listVersionID Attributs wird mit einer Version befüllt
   •    listVersionID multiplicity auf 0..1 setzen
   •    listVersionID "is read only" auf true setzen
•    Bei Nutzung der KoSIT-DocBook-Werkzeuge nun in Datei O/src/informationsmodell/codesUndCodelisten.xml die neue Liste mit
     <include xmlns="http://www.w3.org/2001/XInclude" href="https://www.umweltbundesamt.de/../../build/docBook/dokumente/anhang/code..."/>
     eintragen

Bei Nichtbeachtung drohen folgende Fehler:

•    ruleName = NDR-4: Erlaubte Einbindungsarten für Codelisten
   •    message = The class Data.XUBetrieb.Baukasten.Codes.Code.Abwasserbehandlungsverfahren violates the constraint 'Class.CodeTypesConformToXOEVCodes'.
   •    documentation =
        Ein Code-Datentyp (UML-Klasse mit dem Stereotyp «xsdCode») entspricht mit den Namen, Multiplizitäten und Fix-Werten den Vorgaben zu der Einbindungsart 1, 2, 3 oder 4 von Codelisten.
•    ruleName = NDR-23: Umgang mit Restriktionen über unterschiedliche Namensräume
   •    message = The generalization between Code and Code.Abwasserbehandlungsverfahren violates the constraint 'Generalization.TransNamespaceRestrictionImpliesUnqualifiedElements'.
   •    documentation =
        Bei Restriktionen über mehrere Namensräume müssen die UML-Klasseneigenschaften mit «xsdElement» für die Eigenschaft "form" den Wert "unqualified" aufweisen.
•    ruleName = NDR-28: Valide W3C-XML-Schemata
   •    message = The class Data.XUBetrieb.Baukasten.Codes.Code.Abwasserbehandlungsverfahren violates the constraint 'Class.PropertiesOfNamedTypesAndGlobalElementsAreLocalStructuresElementsOrAttributes'.
   •    documentation =
        Alle UML-Klasseneigenschaften einer «xsdNamedType»- oder «xsdGlobalElement»-UML-Klasse müssen als «xsdLocalStructure», «xsdElement» oder «xsdAttribute» gekennzeichnet sein. Eigenschaften ohne einen dieser Stereotypen sind nicht zulässig.
•    ruleName = NDR-28: Valide W3C-XML-Schemata
   •    message = The attribute listURI of class Data.XUBetrieb.Baukasten.Codes.Code.Abwasserbehandlungsverfahren violates the constraint 'Property.AttributeTypesBasedOnW3CDatatypes'.
   •    documentation =
        Der Typ einer UML-Klasseneigenschaft mit dem Stereotyp «xsdAttribute» ist entweder direkt ein W3C-Datentyp bzw. eine Ableitung eines W3C-Datentyps.
•    ruleName = NDR-28: Valide W3C-XML-Schemata
   •    message = The attribute listURI of class Data.XUBetrieb.Baukasten.Codes.Code.Abwasserbehandlungsverfahren violates the constraint 'Property.InlinePropertiesMustBeTyped'.
   •    documentation =
        Eine UML-Klasseneigenschaft mit dem Stereotyp «xsdElement» oder «xsdAttribute», die als Inline-Klasseneigenschaft innerhalb einer UML-Klasse und nicht als UML-Assoziationsende über einen Rollennamen definiert ist, muss einen Typ besitzen.