=========
Datenkorb
=========


.. contents:: Inhalt

Übersicht
---------

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`` **TODO**

``dc:properties`` **TODO**

``dc:virtual-column`` **TODO**

Datensätze einschränken
~~~~~~~~~~~~~~~~~~~~~~~

``dc:filter`` **TODO**

``dc:group`` **TODO**

Datensätze auffalten
~~~~~~~~~~~~~~~~~~~~

``dc:for-each`` **TODO**

``dc:iterate`` **TODO**

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`.

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.



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**