=========
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
~~~~~~

``dc:macro`` **TODO**

``dc:macro-body`` **TODO**

``dc:call-macro`` **TODO**

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