Mercurial > dive4elements > river
view artifacts/doc/datacage_ref_de.rst @ 7387:cfac25ad6b3e
meta-data.xml: cleanup longitudinal-section-user-prototype, removing dupes.
author | Felix Wolfsteller <felix.wolfsteller@intevation.de> |
---|---|
date | Thu, 17 Oct 2013 09:40:12 +0200 |
parents | e07dc8854a8f |
children | dd87e0a5f83c |
line wrap: on
line source
========= Datenkorb ========= .. contents:: Inhalt Übersicht --------- Der Datenkorb ist im Kern ein Dive4Elements/River eingebetteter Webdienst, der dazu dient, ein XML-Dokument zu generieren, das seinerseits benutzt werden kann, um Daten so identifizierbar zu machen, dass sie zu Projekten innerhalb von Dive4Elements/River hinzugeladen werden können. Das vom Datenkorb erzeugte XML-Dokument wird dann vom D4E/River-Client in eine Baumansicht innerhalb der graphischen Benutzeroberfläche transformiert. Die Grundlage für das XML-Doument, das an die Oberfäche gesandt wird, ist ein XML-Dokument namens ``meta-data.xml``, das im ``conf``-Verzeichnis des Servers als Template für die Ausgabe-XML benutzt wird. Dieses Referenzhandbuch beschreibt die Strukturen innerhalb von ``metadata.xml``. Grundstruktur ------------- Das Grundgerüst einer validen ``meta-data.xml`` sieht sieh so aus: .. code:: xml <xml version="1.0" encoding="UTF-8"> <dc:template xmlns:dc="http://www.intevation.org/2011/Datacage"> <datacage> ... </datacage> </dc:template> Dies erzeugt folgendes Dokument: .. code:: xml <xml version="1.0" encoding="UTF-8"> <datacage> ... </datacage> Elemente, die nicht aus dem Namespace ``dc`` stammen, werden durchkopiert. ``dc``-Elemente dienen der Steuerung des Templating. Generell kann sagen, dass das ``meta-data.xml``-Template mittels einer rekursiven Tiefensuche (siehe http://de.wikipedia.org/wiki/Tiefensuche) über seine Elemente abgearbeitet wird. Daten ----- Im Datenkorb stehen zwei Arten von Daten zur Auswertung zur Verfügung. ``Datensätze`` ~~~~~~~~~~~~~~ Datensätze sind Tabellen mit benannten Spalten. Sie werden von Datenquellen erzeugt und in einem Stapel verwaltet. Die konkreten Werte stehen erst durch Auffaltung als Variablen zur Verfügung. ``Variablen`` ~~~~~~~~~~~~~ Variablen sind die Werte, die aktuell zur Auswertung zur Verfügung stehen. Sie haben einen Namen und einen Typ (String, Zahl, durch Datenquelle bestimmt). Textersatz ---------- Um die Wertebelegungen in das Ausgabedokument schreiben zu kann an entsprechenden Stellen eine String-Interpolation durchgeführt werden. Hier finden zwei Arten von Textersatz ihren Einsatz. ``${}-Ersetzungen`` ~~~~~~~~~~~~~~~~~~~ Die ältere Variante. Innerhalb von Strings werden hier nur Variablen aufgelöst. Beispiel: "**Hallo, ${planet}!**" wird bei planet = 'Welt' zu "**Hallo, Welt!**". ``{$}-Ersetzungen`` ~~~~~~~~~~~~~~~~~~~ Die neuere Variante, allerdings noch nicht komplett an allen Stellen einsatzfähig. Innerhalb der geschweiften Klammern können beliebige XPath-Ausdrück stehen, die zu Strings evaluiert werden. Dies orientiert sich an den String-Auswertungen in XSLT. "**{ concat($greet, ', ', $planet, '!') }**" wird bei gesetzten Variablen greet = Hallo und planet = "Welt" zu **Hallo, Welt!** ausgewertet. Datenkorb-Elemente ------------------ Datensätze erzeugen ~~~~~~~~~~~~~~~~~~~ ``dc:context`` Aufspannen eines Gültigkeitsbereiches eines Datenbankdatensatz ............................................................................. .. code:: xml <dc:context connection="Verbindung"> ... </dc:element> Spannt einen Gültigkeitsbereich für einen Datensatz auf, der aus der Datenbank kommt. Die adressierte Datenbank wird über das optionale Attribut 'connection' bestimmt. Zur Zeit sind drei Datenbanken angebunden: - **user**: Die Index-Datenbank des Artefakt-Servers. Hierüber stehen Meta-Informationen zu alten Berechnungen zur Verfügung. - **system**: Die FLYS-Datenbank mit den hydrologischen, morphologische und geodätischen Daten. - **seddb**: Die Sediment-Datenbank. In einem `<dc:context>`-Element wird zwingend ein `<dc:statement>`-Element erwartet, um einen Datensatz aus der Datenbank zu holen. Dieser Datensatz steht dann innerhalb des `<dc:context>`-Elementes ein oder mehrfach zur Verfügung. Innerhalb eines `<dc:context>`-Elementes können weitere `<dc:context>`-Elemente eingeschachtelt werden. Ist kein 'connection'-Attribut vorhanden, wird die Datenbank-Verbindung des umgebenen Kontextes weiterbenutzt. Initial wird je nach Aufrufart der Datenkorbs entweder der **user** oder **system**-Kontext angenommen. Dies richtet sich danach, ob in der Aufrufumgebung eine Artefakt gesetzt wird oder nicht. Im ersten Fall wird angenommen, dass es sich um einen Ladevorgang für zusätzliche Daten handelt, die auch alte Berechnungen mit einschliesst. ``dc:statement`` Holen eines Datensatzes aus einer Datenbank ............................................................ .. code:: xml <dc:statement> SQL-Select-Statement. </dc:element> Mittels eines SQL-Select-Statements werden in einem `<dc:context>`-Elementes aus der dort definierten Datenbank geholt. Die Spaltennamen der Projektion des SQL-Statements werden übernommen und später beim Auffalten des Datensatzes benutzt. ``dc:container-context`` Tabellarische Daten aus der Programm-Umgebung ...................................................................... **TODO** ``dc:properties`` **TODO** ``dc:virtual-column`` Virtuelle Spalten definieren .................................................. .. code:: xml <dc:virtual-column name="Name" type="Type" expr="XPath-Ausdruck"> ... </dc:virtual-column> Definiert eine neue, virtuelle Spalte namens Name für den aktuellen Datensatz. Der Typ wird optional durch Typ festgelegt; ohne Angabe wird der Typ String angenommen. Die Wertebelegung ergibt sich aus der zeilenweisen Auswertung des XPath-Ausdrucks. Dies sei an folgendem Beispiel illustriert: +----+ +Zahl+ +====+ + 1+ +----+ + 2+ +----+ + 3+ +----+ .. code:: xml <dc:virtual-column name="Quadrat" type="number" expr="$Zahl * $Zahl"> ... </dc:virtual-column> Erzeugt einen neuen Datensatz folgender Struktur: +----+-------+ +Zahl+Quadrat+ +====+=======+ + 1+ 1+ +----+-------+ + 2+ 4+ +----+-------+ + 3+ 9+ +----+-------+ Innerhalb eines `virtual-column`-Elementes kann der Datensatz mittel `dc:for-each` wie gewohnt realisiert werden. Wird das `dc:virtual-column`-Element verlassen, gilt wieder der vormalige Datensatz ohne die zusätzlich Spalte. Datensätze einschränken ~~~~~~~~~~~~~~~~~~~~~~~ ``dc:filter`` Selektieren einzelner Zeilen aus dem aktuellen Datensatz ...................................................................... .. code:: xml <dc:filter expr="XPath-Ausdruck"> ... </dc:filter> Evaluiert pro Zeile des aktuellen Datensatzes den XPath-Ausdruck 'expr' und erzeugt einen neuen Datensatz, der nur die Zeilen des Originaldatensatzes enthält für den die Auswertung logisch wahr ergab. Im XPath-Ausdruck stehen die aufgefalteten Werte der jeweiligen Zeile zur Verfügung. Folgends Beispiel soll dies verdeutlichen: +----+ +Zahl+ +====+ + 1+ +----+ + 2+ +----+ + 3+ +----+ + 4+ +----+ Zahlen erhalten, die einen Wert kleiner drei haben. .. code:: xml <dc:filter expr="$Zahl < 3"> ... <dc:filter> Dies erzeugt folgenden neuen Datensatz: +----+ +Zahl+ +====+ + 1+ +----+ + 2+ +----+ Innerhalb des `dc:filter`-Elementes kann der neue Datensatz wie gewohnt mit `dc:for-each` realisiert werden. Nach Verlassen des `dc:filter`-Elementes ist wieder der vormalige Datensatz aktuell. ``dc:group`` Datensätzen in Gruppen ordnen .......................................... .. code:: xml <dc:group expr="XPath-Ausdruck"> ... </dc:group> Pro Zeile der Originaldatensatzes wird der XPath-Ausdruck 'expr' ausgewertet. Wie bei `dc:filter` stehen hier die aufgefalteten Werte der einzelnen Spalten zur Verfügung. Das Resultat der XPath-Auswertung wird als Schlüssel für zu erzeugende Gruppen benutzt, denen dann die Zeilen zugeordnet werden. Nachdem alle Zeilen ihren entsprechenden Gruppen zugeordnet wurden, wir der Inhalt des `dc:group`-Elements für jede Gruppe durchlaufen. Innerhalb des `dc:group`-Elementes steht der jeweilige Schlüssel der aktuellen Gruppe über die Funktion `dc:group-key()` zur Auswertung zu Verfügung. Innerhalb der jeweiligen Gruppen kann mittel `dc:for-each` der jeweilige Unterdatensatz realisiert werden. Zur Verdeutlichung folgendes Beispiel: +-------+-----------+ +Marke +Bezeichnung+ +=======+===========+ +Ferrari+Testarossa + +-------+-----------+ +Volvo +V40 + +-------+-----------+ +Volvo +780 + +-------+-----------+ +Ferrari+F40 + +-------+-----------+ +VW +Käfer + +-------+-----------+ .. code:: xml <marken> <dc:group expr="$Marke"> <marke name="{dc:group-key()}"> <dc:for-each> <bezeichnung name="$Bezeichnung"/> </dc:for-each> </marke> </dc:group> </marken> Dies führt zu folgender Ausgabe: .. code:: xml <marken> <marke name="Ferrari"> <bezeichnung name="F40"/> <bezeichnung name="Testarossa"/> </marke> <marke name="Volvo"> <bezeichnung name="V40"/> <bezeichnung name="780"/> </marke> <marke name="VW"> <bezeichnung name="Käfer"/> </marke> </marken> Datensätze auffalten ~~~~~~~~~~~~~~~~~~~~ ``dc:for-each`` Realisieren eines Datensatzes ............................................. .. code:: xml <dc:for-each> ... <dc:for-each> Erzeugt nacheinander alle zeilenweisen Realisationen des aktuellen Datensatzes. Die einzelnen Spaltenwerte sind dann über Variablen erreichbar, die nach den Spaltenbezeichnern des Datenstzes benannt sind. Folgendes Beispiel soll den Sachverhalt illustieren: +----+ +Zahl+ +====+ + 1+ +----+ + 2+ +----+ + 3+ +----+ .. code:: xml <zahlen> <dc:for-each> <zahl wert="$Zahl"/> <dc:for-each> </zahlen> Dies erzeugt folgende Ausgabe: .. code:: xml <zahlen> <zahl wert="1"/> <zahl wert="2"/> <zahl wert="3"/> </zahlen> ``dc:iterate`` **TODO** Bedingte Ausführung ~~~~~~~~~~~~~~~~~~~ ``<dc:if>`` Einfaches Wenn-Dann ohne Sonst-Fall ............................................... .. code:: xml <dc:if test="XPath-Ausdruck"> ... </dc:if> Der innere Teil wird nur dann betreten, wenn der XPath-Ausdruck zu logisch wahr evaluiert wird. Dieses Konstrukt kennt keinen alternativen Pfad, der betreten wird, falls der Ausdruck zu logisch falsch ausgewertet wird. Wird dies benötigt, muss man ``<dc:choose>`` benutzen. ``<dc:if>`` ist in Symmetrie zu ``<xsl:if>`` von XSLT entworfen worden. ``<dc:choose>`` Ketten von Wenn-Dann-Ausdrücken ............................................... .. code:: xml <dc:choose> <dc:when test="XPath-Ausdruck 1"> ... </dc:when> <dc:when test="XPath-Ausdruck 2"> ... </dc:when> ... <dc:otherwise> ... </dc:otherwise> </dc:choose> Es werden der Reihe nach von oben nach unter die ``test``-XPath-Ausdrücke der ``dc:when``-Elemente ausgewertet. Evaluiert ein Ausdruck zu logisch wahr, wird der innere Teil des entsprechenden ``<dc:when>``-Elements betreten. Die verbliebenen ``<dc:when>``- und ``<dc:otherwise>``-Elemente werden dann ignoriert. Evaluiert keiner der ``test``-Ausdrücke zu wahr, wird der innere Teil des ``<dc:otherwise>``-Elements betreten. ``<dc:choose>`` ist in Symmetrie zu ``<xsl:choose>`` von XSLT entworfen worden. Makros ~~~~~~ Um innerhalb des Definitionsdokumentes Wiederholungen zu vermeiden, können sogenannte Makros definiert werden, die dann von anderer Stellen aus eingefügt werden können. ``dc:macro`` Wiederverwendbare Teile definieren ............................................... .. code:: xml <dc:macro name="Name"> ... </dc:macro> Definiert ein Makro namens Name. Nach der Definition ist dieses dann unter diesem Namen global innerhalb des Definitionsdokumentes bekannt. Makros können geschachtelt werden. Auch eingeschachtelte Makros sind global sichtbar. Die Makrodefinition und ihre eingeschalteten Elemente werden nicht in das Ausgabedokument übernommen. ``dc:call-macro`` Makros aufrufen .. code:: xml <dc:call-macro name="Name"> Ruft ein Makro names Name auf. Dieses muss mit `dc:macro` definiert sein. Die Reihenfolge von Definition und Aufruf ist egal. ``dc:macro-body`` Elemente an ein Makro übergeben ................................................. .. code:: xml <dc:macro name="Name"> ... <dc:macro-body/> ... </dc:macro> Um an Makros weitere Bausteine als Argument übergeben zu können, ist es optional möglich innerhalb einer Makrodefinition ein Element `dc:macro-body` einzufügen. Dieses Element expandiert sich zum Inhalt des `dc:call-macro`-Aufrufs. .. code:: xml <dc:call-macro name="Name">Inhalt von dc:macro-body</dc:call-macro> Zur Verdeutlichung ein konkretes Beispiel .. code:: xml <dc:macro name="Greetings"> <Hallo> <dc:macro-body/> </Hallo> </dc:macro> <dc:call-macro name="Greetings">Welt</dc:call-macro> <dc:call-macro name="Greetings">Mond</dc:call-macro> Dies produziert folgende Ausgabe .. code:: xml <Hallo>Welt</Hallo> <Hallo>Mond</Hallo> Das Haupteinsatzgebiet dieses Konstruktes ist die transparente Bereitstellung von Kontexten, die dann verschiedentlich ausgewertet werden sollen. Sonstige Elemente ~~~~~~~~~~~~~~~~~ ``dc:element`` Hinzufügen neuer Elemente in der Ausgabe ....................................................... .. code:: xml <dc:element name="Name"> ... </dc:element> Erzeugt ein Element namens Name. Für den Namen gelten die `${}-Ersetzungen`_. ``dc:attribute`` Hinzufügen neuer Attribute zum umgebenden Ausgabeelement ......................................................................... .. code:: xml <dc:attribute name="Name" value="Wert"/> Fügt dem umgebenden Ausgabeelement ein weiteres Attribut namens Name mit dem Wert von Wert hinzu. Für Namen und Wert gelten die `${}-Ersetzungen`_. Der Einsatz dieses Konstrukts findet häufig im Zusammenhang mit dc:element seinen Einsatz, wenn es ein Ausgabeelement vollständig aus Variablenbelegungen erstellt werden soll. ``dc:comment`` Kommentare im Beschreibungsdokument .................................................. .. code:: xml <dc:comment> ... </dc:comment> Ein Kommentar auf Ebene des Beschreibungsdokumentes, das keinerlei Ausgabe im Ausgabedokument erzeugt. Eingeschachtelte Elemente werden ebenfalls nicht ausgewertet. Im Gegensatz dazu werden die XML-typischen **<!-- Kommetare -->** in das Ausgabedokument übernommen! ``dc:message`` Ausgabe auf die Diagnoseausgabe (Log) .................................................... .. code:: xml <dc:message> Text für die Diagnose. </dc:message> Gibt den Text innerhalb des Elementes aus Ausgabe im Log aus. Dies dient in erster Linie dem Nachvollziehen von Aufrufen innerhalb des Datenkorbdokumentes. Für den Text gelten die `{$}-Ersetzungen`_. ``dc:variable`` Erzeugung einer kontext-lokalen Variablen ......................................................... .. code:: xml <dc:variable name="Name" type="Typ" expr="XPath-Ausdruck"/> Legt im aktuellen Kontext eine lokale Variable namens Name an. Diese hat den Typ Typ und entsteht durch Auswertung des XPath-Ausdruck expr. Der Typ ist optional. Wird dieser nicht gesetzt, wird das Ergebnis als String interpretiert. Alternativ können hier die Werte 'number' für Zahlen, 'bool' für Boolean-Werte benutzt werden. Für den Namen und den Typ gelten die `${}-Ersetzungen`_. Wird der aktuellen `dc:context` verlassen, ist diese Variable nicht mehr definiert. ``dc:convert`` kontext-lokale Konvertierung von Variablen ......................................................... .. code:: xml <dc:convert name="Name" type="Typ"/> Konvertiert die Variable namens Name für die Gültigkeit des aktuellen Kontextes in einen anderen Typ. Für Name und Typ gelten die `${}-Ersetzungen`_. Für die Typen gilt das gleiche wie für die Typen von `dc:variable`. Datenkorb-Funktionen -------------------- ``dc:contains`` **TODO** ``dc:fromValue`` **TODO** ``dc:toValue`` **TODO** ``dc:replace`` **TODO** ``dc:replace-all`` **TODO** ``dc:has-result`` **TODO** ``dc:group-key`` **TODO** ``dc:date-format`` **TODO** ``dc:dump-variables`` **TODO** ``dc:get`` **TODO**