Parameter und Sequenzen
Es ist wichtig die Beziehung zwischen Parametern und Sequenzen zu beachten und zu wissen, wie Parameter und Sequenzen in XPath-Ausdrücken verwendet werden. Die folgenden Definitionen sollten diese Beziehungen verdeutlichen:
•Eine Sequenz besteht aus Objekten, bei denen es sich entweder um atomare Werte oder Nodes handelt. Die Objekte der Sequez werden mittels Kommas getrennt.
•Eine XPath-Funktion kann Parameter erhalten. So ist z.B. im XPath 2.0-Ausdruck count($a)der Teil innerhalb der Klammern der Funktion der Parameter der Funktion und muss eine Sequenz von Objekten sein.
•Ein Argument besteht aus einem oder mehreren Objekten in einem Funktionsaufruf. So hat z.B. die Funktion count(//Person) ein Argument: //Person. Dieses Argument ist gültig, weil es eine Node-Sequenz zurückgibt, die der Signatur der count() Funktion entspricht. (Die Signatur einer Funktion definiert die Anzahl der Parameter und den erwarteten Datentyp der einzelnen Parameter. Außerdem definiert sie, was die Funktion zurückgibt sowie den Datentyp des zurückgegebenen Objekts).
•Die Funktion substring('StyleVisionExamples', 6, 6)- die den String Vision zurückgibt - hat drei Argumente und ist laut der Signatur der substring() Funktion gültig und wird von dieser Funktion definiert. Wenn ein Funktionsaufruf mehrere Argumente hat, werden diese durch Kommas voneinander getrennt.
Klammern als Sequenz-Trennzeichen
Beachten Sie beim Erstellen von XPath-Ausdrücken unbedingt Folgendes: Klammern werden zum Trennen von Sequenzen verwendet, in denen zum Enumerieren von Sequenzen das Komma-Trennzeichen oder ein Bereichsoperator verwendet wird. Folglich wird jede durch Klammern getrennte Sequenz (in Funktionsdefinitionen) als ein einziger Parameter bzw. (in Funktionsaufrufen) als ein einziges Argument gelesen.
Ein Path- (oder Locator)-Ausdruck muss nicht unbedingt in Klammern gesetzt werden, da ein XPath-Ausdruck (Beispiel für einen XPath-Ausdruck //Person/@salary) in einem Argument eindeutig als ein einziger Parameter bzw. ein einziges Argument gelesen werden kann. Es handelt sich um einen Parameter/ein Argument, der/das aus einer einzigen Sequenz besteht.
Hier finden Sie ein paar Beispiele zur Veranschaulichung der obigen Punkte:
•avg((10, 20, 30)) Die XPath 2.0-Funktion avg verwendet eine Sequenz von Objekten als ihr einziges Argument. Da es sich bei dieser Sequenz um eine durch Kommas getrennte Enumeration handelt, wird das innere Klammerpaar zum Trennen der obligatorischen einzigen Sequenz benötigt. Ohne die inneren Klammern hätte das Argument drei Argumente und wäre daher ungültig. (Das äußere Klammernpaar sind die Klammern der Funktion.)
•avg(//Person/@salary) Mit diesem XPath-Ausdruck werden die salary-Attribut-Nodes aller Person-Elemente ausgewählt. Ihre Attributwerte werden als die auszuwertende Sequenz zurückgegeben (d. h. es soll der Mittelwert errechnet werden). Es sind keine Klammern notwendig, weil die Sequenz vor der Auswertung nicht enumeriert ist. Das Argument ist der einzige XPath (oder Locator)-Ausdruck. Der XPath-Ausdruck wird ausgewertet und die Rückgabewerte werden als die Elemente einer Sequenz an die Funktion übergeben.
•count((10 to 34))Dies ist eine Enumeration über den Bereichsoperator. Der Bereichsoperator 'to' generiert eine Sequenz von kommagetrennten Objekten (die Ganzzahlen von 10 bis 34), bevor das Argument gelesen wird. Als Ergebnis hat die count() Funktion in Ihrem Argument eine kommagetrennte Sequenz von 25 Objekten. Damit diese als ein aus einer einzigen Sequenz bestehendes Argument gelesen wird, werden Klammern als Trennzeichen benötigt. Ohne diese Klammern hätte der Funktionsaufruf 25 Argumente anstelle von einem, wodurch der Funktionsaufruf ungültig würde, da die count() Funktion gemäß ihrer Signatur nur ein Argument akzeptiert.
•count((10 to 34, 37)) Die inneren Klammern geben an, dass es sich bei allen Objekten innerhalb davon um das einzige Argument des Funktionsaufrufs handelt - nämlich eine Sequenz bestehend aus 26 Elementen.
•count(//Person) Rund um dieses einzige Argument werden keine Klammern zum Trennen der Sequenz benötigt. Beim Argument handelt es sich um einen XPath-Ausdruck, der die //Person Nodes im XML-Dokument sammelt und diese Nodes als Objekte der zu zählenden Sequenz zurückgibt.
Verwendung von XPath-Parametern in XPath-Funktionen
Wenn Parameter in der Definition einer benutzerdefinierten XPath-Funktion verwendet werden, stellen Sie sicher, dass (i) die Anzahl der Argumente in einem Funktionsaufruf dieser XPath-Funktion korrekt ist und (ii) das Ergebnis der Auswertung der Argumente dem erwarteten Typ und den erwarteten Instanzen entspricht.
In der Abbildung oben sind (im Bereich Parameter) drei Parameter definiert, die anschließend (im Bereich Funktionsrumpf) zum Definieren einer XPath-Funktion verwendet werden.
Jeder unter Parameter definierte Parameter kann als Einzelsequenz betrachtet werden. Die Anzahl von Objekten, die innerhalb dieser Sequenz zulässig sind, wird mit der Eigenschaft Instanzen angegeben. In der obigen Definition ist zum Beispiel jeder Parameter (in seiner Eigenschaft Instanzen) als eine Einzelsequenz (das heißt, als Sequenz mit genau einem Objekt) definiert. Jedes Argument muss daher als eine Sequenz bestehend aus einem Objekt betrachtet werden. Die Eigenschaft Type definiert den Datentyp der Objekte der Sequenz.
In der Definition unserer XPath-Beispielfunktion (im Bereich Funktionsrumpf) liefert jeder Parameter ein Element der Sequenz, deren Mittelwert zu errechnen ist. Da die XPath-Parameter zusammen eine Sequenz bilden, muss die Sequenz in Klammern gesetzt werden, um sicherzustellen, dass die gesamte Sequenz als ein einziger Parameter der avg() Funktion gelesen wird. Wenn eines der Argumente im Funktionsaufruf (die den drei Parametern entsprechen) zur Laufzeit keine Einzelsequenz ist, wird ein Fehler zurückgegeben.
Im Folgenden finden Sie Beispiele für die Verwendung von XPath-Parametern in Aufrufen der XPath-Funktion ThreeAverage(), die in der obigen Abbildung zu sehen ist. Sie können in der Design-Ansicht eine automatische Berechnung einfügen und ihr die unten aufgelisteten XPath-Ausdrücke zuweisen, um die Ergebnisse zu sehen. Die Funktion wurde als bestehend aus einer Sequenz von drei Ganzzahlen definiert, deren Mittelwert berechnet werden soll.
•sps:ThreeAverage(10,20,30) gibt 20 zurück. Es gibt drei gültige Argumente im Funktionsaufruf, die den drei XPath-Parametern entsprechen.
•sps:ThreeAverage( (10),(20),(30) ) Es gibt drei gültige Eingabeargumente, die den drei XPath-Parametern entsprechen. Jedes Eingabeargument steht innerhalb von Klammern (die redundant, aber kein Fehler sind, da jede Sequenz eine Einzelsequenz ist).
•sps:ThreeAverage( (10),20,30 ) gibt 20 zurück. Es gibt drei gültige Eingabeargumente, die den drei XPath-Parametern entsprechen. Der erste Argument steht innerhalb von Klammern (dies ist nicht notwendig, aber kein Fehler).
•sps:ThreeAverage( (10,20),(30),(40) ) gibt einen Fehler zurück, weil das erste Argument ungültig ist. Es handelt sich nicht um eine Einzelsequenz, wie in der Definition der Eigenschaft des ersten $a-Parameters ('Genau eines')' gefordert.
•sps:ThreeAverage( (10,20,30) ) gibt einen Fehler zurück, weil innerhalb der Klammern nur ein Argument übergeben wird. Außerdem ist das Argument ungültig, weil es sich bei der Sequenz nicht um eine Einzelsequenz handelt.
Wenn die Eigenschaft Instanzen eines Parameters auf Mindestens eines gesetzt wird (wie in der Definition in der Abbildung unten gezeigt), dann wird dieser Parameter als Sequenz bestehend aus einem oder mehreren Objekten definiert.
In der obigen Definition wurde der erste Parameter als Sequenz von einem oder mehreren Objekten und die nächsten beiden als Einzelsequenzen definiert. Die Funktion wurde so definiert, dass die Anzahl der Objekte, die vom ersten Parameter übergeben werden, ermittelt wird, das Resultat zu den beiden Integer-Werten, die von den beiden Parametern übergeben werden, hinzugefügt und dann das Resultat durch drei dividiert wird, um den Durchschnitt zu erhalten. Beachten Sie Folgendes:
•Die Sequenz, die der Parameter der avg()-Funktion ist, steht innerhalb von Klammern. Damit wird angegeben, dass die avg()-Funktion eine Einzelsequenz enthält, die aus drei Objekten besteht, die die Parameter bilden. Die Einzelsequenz besteht aus drei Integer-Werten: dem ersten, der von der count()-Funktion übergeben wird; und dem zweiten und dem dritten Wert, also den Parametern b und c.
•Das Argument der count() Funktion steht nicht innerhalb von Klammern zum Trennen der Sequenz, da es sich beim Argument eindeutig um eine Einzelsequenz handelt.
Hier finden Sie Beispiele zur Verwendung von Parametern in Aufrufen der oben gezeigten XPath-Funktion Average().
•sps:Average((1,2),3,4) gibt 3 zurück. Es gibt drei gültige Eingabeargumente, die den drei Parametern entsprechen. Das erste Argument steht zur Abgrenzung innerhalb von Klammern. Wenn die count()-Funktion damit operiert, gibt die Funktion den Wert 2 zurück. Dieser Wert ist das erste Objekt der Sequenz, die an die avg()-Funktion übergeben wird.
•sps:Average( 4,4,4 ) gibt 3 zurück. Es gibt drei gültige Eingabeargumente. Das erste Argument darf eine Sequenz bestehend aus einem Objekt sein (siehe die Eigenschaft Instanzen des entsprechenden Parameters). Es werden keine Klammern benötigt um separate Argumente anzugeben.
Weitere interessante Punkte
Die folgenden zusätzlichen Punkte sollten beachtet werden:
•Wenn ein Parameter mit Mindestens einer-Instanz definiert ist, könnte eine Funktion wie MyAverage() mit einem XPath-Ausdruck wie avg(($a)) definiert werden. Diese Funktion würde ein Argument, das eine Einzelsequenz bestehend aus einem oder mehreren Objekten ist, akzeptieren. Die Funktion könnte wie folgt aufgerufen werden: sps:MyAverage((2,3,4)) und würde den Wert 3 zurückgeben. Das Eingabeargument muss in Klammern eingeschlossen werden, um sicherzustellen, dass die Eingabe als Einzelsequenz und nicht als drei einzelne Sequenzen gelesen wird (was der Fall sein würde, wenn die Objekte nicht in Klammern stünden).
•Wenn ein XPath-Parameter $a mit einer Keines oder eines-Instanz definiert ist, könnte eine Funktion wie MyAverage() mit einem XPath-Ausdruck wie avg(($a, $b, $c)) definiert werden. Diese Funktion würde drei Sequenzen als ihr Argument akzeptieren, wobei die Möglichkeit besteht, dass die erste Sequenz leer ist. Wenn die erste Sequenz leer sein soll, dann muss die leere Sequenz explizit als erstes Eingabeargument übergeben werden. Andernfalls wird ein Fehler ausgegeben. Wenn die Funktion wie folgt aufgerufen würde: sps:MyAverage(30,20,10), würde sie den Wert 20 zurückgeben. Die Funktion könnte auch mit sps:MyAverage((),20,10) aufgerufen werden und würde den Wert 15 zurückgeben (beachten Sie, dass die leere Sequenz als Eingabewert "leer" gezählt wird). Folgendes würde jedoch einen Fehler generieren: sps:MyAverage(20,10), weil keine leere erste Sequenz geliefert wird und das dritte Argument daher als fehlend betrachtet wird.
Komplexe Beispiele
Neben dem Vorteil der Wiederverwendung eines XPath-Ausdrucks ermöglichen benutzerdefinierte XPath-Funktionen auch die Konstruktion von komplexen, angepassten XPath-Funktionen, die nicht im Funktionsumfang von XPath 2.0 enthalten sind. Zum Beispiel könnte eine faktorielle Funktion einfach mit einem XPath-Ausdruck erstellt werden, die eine Einzelsequenz als ihren einzigen Parameter hat. Wenn der Parameter $num die Zahl ist, von der der Faktor gebildet werden soll, dann würde der XPath-Ausdruck zum Erstellen der Funktion so aussehen:
if ($num < 2) then 1 else $num * sps:factorial($num - 1)
Wenn diese Funktion den Namen Factorial() hätte, dann könnte der Faktor von beispielsweise 6 berechnet werden, indem die Funktion mit sps:Factorial(6) aufgerufen würde.