Beispiel: Import einer benutzerdefinierten XQuery-Funktion
In diesem Beispiel wird gezeigt, wie Sie eine XQuery-Demobibliothek in MapForce importieren und deren Funktionen über ein Mapping aufrufen. Das Demomodul in diesem Beispiel besteht aus nur einer Funktion, die anhand von Dezimalbeträgen eine 20%ige Steuer berechnet. In einer Produktionsumgebung kann ein XQuery-Modul mehrere Funktionen enthalten.
Alle im XQuery-Modul deklarierten Funktionen müssen atomare Typen zurückgeben und auch ihre Parameter müssen atomare Datentypen sein, da das Modul sonst nicht in MapForce importiert werden kann. |
Das XQuery-Demomodul befindet sich auf dem Rechner, auf dem MapForce installiert ist, unter dem folgenden Pfad relativ zu Ihrem persönlichen Ordner "Dokumente" : <Dokumente>\Altova\MapForce2024\MapForceExamples\module.xq.
xquery version "1.0"; |
module.xq
Nachdem Sie die XQuery-Moduldatei in MapForce importiert haben, können Sie die Funktion demo:calculatetax von einem Mapping aus aufrufen. Beachten Sie, dass die Berechnung der Steuer mit Hilfe einer XQuery-Funktion nur zu Demozwecken erfolgt. Dasselbe Ergebnis können Sie auch mit Hilfe von vordefinierten MapForce-Funktionen erzielen.
Unter dem folgenden Pfad finden Sie ein Demo-Mapping, das die Funktion demo:calculatetax aufruft: <Dokumente>\Altova\MapForce2024\MapForceExamples\CalculateTax_XQuery.mfd. Wenn Sie dieses Mapping anfangs öffnen, zeigt MapForce eine Warnmeldung an, dass eine oder mehrere Komponenten darin enthalten sind, die in XQuery nicht zur Verfügung stehen. Diese Warnung ist normal, da sie auftritt, wenn im Mapping eine Funktion von einer benutzerdefinierten XQuery-Bibliothek aus referenziert wird, die noch nicht importiert wurde. Damit die Warnung nicht mehr angezeigt wird, werden wir das fehlende XQuery-Modul in MapForce, wie unten gezeigt, importieren.
So importieren Sie das XQuery-Modul in MapForce:
1.
1.Klicken Sie im unteren Bereich des Fensters Bibliotheken auf die Schaltfläche Bibliotheken hinzufügen/entfernen. Daraufhin wird das Fenster Bibliotheken verwalten geöffnet (siehe Abbildung unten).
2.Um Funktionen als lokale Bibliothek (nur im Geltungsbereich des aktuellen Dokuments) zu importieren, klicken Sie auf die Schaltfläche Hinzufügen unterhalb des aktuellen Mapping-Namens. Um Funktionen als globale Bibliothek (auf Programmebene zu importieren, klicken Sie auf die Schaltfläche Hinzufügen neben Globale Bibliotheksimporte. Wenn Sie eine Bibliothek lokal importieren, können Sie den Pfad zur Bibliotheksdatei als relativ zur Mapping-Datei definieren. Bei gobal importierten Bibliotheken ist der Pfad zur importierten Bibliothek immer absolut.
3.Navigieren Sie zu <Dokumente>\Altova\MapForce2024\MapForceExamples\module.xq und klicken Sie auf Öffnen. Daraufhin erscheint ein Meldungsfeld, in dem Sie darüber informiert werden, dass eine neue Bibliothek hinzugefügt wurde.
Die importierte Bibliothek und die Funktion demo:calculatetax werden nun im Fenster "Bibliotheken" angezeigt.
Das Mapping kann nun ohne Warnungen validiert und ausgeführt werden. Die Funktion demo:calculatetax in der Abbildung unten stammt aus dem importierten XQuery-Modul und kann wie jede andere vordefinierte Funktion zum Mapping hinzugefügt werden, siehe Hinzufügen einer Funktion zum Mapping.
CalculateTax_XQuery.mfd
Erläuterung des Mappings
Das oben gezeigte Mapping CalculateTax_XQuery.mfd erhält als Input eine XML-Datei, in der Artikel gespeichert sind. Jeder Artikel verfügt über einen einzigen Preis, der in Form eines Dezimalwerts angegeben ist, z.B.:
<Articles> |
Articles.xml
Die mit dem Mapping erzeugte XML-Datei, die demselben Schema wie die XML-Quelldatei entspricht. Daher haben Quell- und Zielkomponente im Mapping dieselbe Struktur. Wie Sie an den Mappingverbindungen sehen, wurden fast alle Elemente direkt von der Quellkomponente auf die Zielkomponente gemappt - so gibt es z.B. für jedes Element Article in der Quellkomponente ein Article-Element in der Zielkomponente. Die Werte aller Datenelemente werden unverändert von der XML-Quelldatei kopiert. Die einzige Ausnahme ist SinglePrice. Der Wert von SinglePrice wird mit Hilfe zweier Funktionen berechnet:
•Die XQuery-Funktion demo:calculatetax berechnet den Steuerbetrag anhand des ursprünglichen SinglePrice-Elements als Input.
•Die vordefinierte MapForce Funktion add fügt den Steuerbetrag zum ursprünglichen SinglePrice-Betrag hinzu und gibt den Endbetrag zurück.
Beachten Sie, dass der Datentyp des Datenelements SinglePrice xs:decimal ist. Dies entspricht dem Input-Parametertyp und dem Rückgabetyp der XQuery-Funktion.
Unten sehen Sie das Ergebnis, das bei Klick auf das Fenster Ausgabe erzeugt wird. Beachten Sie, dass jeder Preis im Vergleich zur XML-Quelldatei um 20% erhöht wurde.
