function-available

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

   

Kategorie: Information über die Laufzeitumgebung

Herkunft: XSLT 1.0

Rückgabewert: Ein boolescher Wert, true oder false, je nachdem, ob die angefragte Funktion in der Laufzeitumgebung verfügbar ist oder nicht.

Aufruf/Argumente:

function-available($funktionsname, $arity?)

$funktionsname:
Obligatorisch. Ein String xs:string, der als Name der Funktion interpretiert wird. Der String wird als QName verstanden, dessen expandierte Form dem expandierten QName der (Erweiterungs-)Funktion ent­sprechen muss. Das Argument muss, wenn es als Literal übergeben wird, in Stringbegrenzer eingeschlossen sein. (Es ist stets möglich, jedoch selten sinn­voll, hier einen XPath-Ausdruck zu übergeben, der den String erzeugt. Ergibt dies jedoch keinen lexikalischen QName, so gibt die Funktion false zurück.)

$arity: (neu in XSLT 2.0)
Optional. Eine Ganzzahl xs:integer, die der Arity, also der Anzahl der erwarteten Argumente der überprüften Funktion entsprechen muss. Dieses Argument steht in XSLT 1.0 nicht zur Verfügung.

Verwendungszweck:

Die Funktion function-available() prüft, ob eine Funktion in der aktuellen Laufzeitumgebung des Stylesheets verfügbar ist oder nicht. Der beim Aufruf übergebene String wird als QName der Funktion interpretiert. Solange kein zweites Argument übergeben wird, ist der Test erfolgreich, wenn eine Funktion dieses Namens im Scope ist, ungeachtet der Anzahl der von ihr erwarteten Argumente.

Besitzt der Namensstring der so bezeichneten Funktion keinen Präfixanteil, so wird sie als im XSLT-Namensraum befindlich betrachtet. In diesem Fall muss es sich um eine gültige XSLT- oder XPath-Core-Funktion handeln.

Eine durch den Prozessorhersteller definierte Erweiterungsfunktion oder durch den User mit xsl:function deklarierte Stylesheet-Funktion muss dage­gen immer ein Präfix besitzen, dessen Namensraum Nicht-Null und ungleich dem Default-Namensraum ist.

Mittels des optionalen zweiten Arguments kann die Argumentzahl (arity) der abgetesteten Funktion abgeglichen werden. Der Test ist nur dann erfolgreich, wenn die Funktion existiert und die geforderte Anzahl von Argumenten entgegennimmt (Achtung, dieses Argument steht nur in XSLT 2.0 zur Verfügung).

Wichtig ist diese Testfunktion in Zusammenhang mit abwärtskompatibler Stylesheetverarbeitung, um im Fall der Nichtverfügbarkeit einer Funktion ein Fallback-Verhalten zu gewährleisten (siehe Beispiel 4).

Das Vorhandensein des Aufrufs einer nicht verfügbaren Funktion innerhalb eines XPath-Ausdrucks ist von vornherein kein Fehler – solange dieser Ausdruck nicht verarbeitet wird (in diesem Fall ergäbe sich in der Tat ein Laufzeitfehler). Um dies abzufangen, wird man function-available() einsetzen.

Statische Fehler, die beim Einlesen des Stylesheets für einen vom Prozessor ausgewerteten Kontext gemeldet werden (siehe Beispiel 6), können durch function-available() in Verbindung mit dem use-when-Attribut verhindert werden, indem bereits das Einlesen des Blocks unterbunden wird.

Achtung – Nur die Existenz und Arity der Funktion wird überprüft!
Der Test stellt lediglich sicher, dass eine Funktion mit dem ange­fragten Bezeichner existiert und, sofern die Arity getestet wird, sie mit der erforderlichen Zahl von Argumenten arbeiten kann. Nicht gewährleistet ist, dass diese Funktion anschließend erfolgreich aufgerufen wird: Es gibt kei­nen Weg, die von der Funktion für ihre Argumente geforderten Datentypen im Vorfeld in Erfahrung zu bringen.
Zudem ist bei der Deklaration von Stylesheet-Funktionen durch das override-Attribut die Möglichkeit gegeben, einer (gleichnamigen!) herstellerdefinier­ten Erweiterungsfunktion den Vorrang zu erteilen. Diese verhält sich unter Umständen vollständig anders als die eigentlich gewünschte Funktion, kann jedoch durch function-available() von dieser nicht unterschieden wer­den.

Beispiele:

Beispiel 1 – Test einer existierenden XSLT-Funktion:

function-available('format-number')

Es handelt sich bei format-number() um eine in XSLT verfügbare Funktion, daher wird in diesem Fall der Wert true zurückgegeben.

Beispiel 2 – Test einer nicht existierenden XSLT-Funktion:

function-available('neue-funktion')

Da bei der Abfrage kein Präfix verwendet wurde, wird eine XSLT-Funktion angenommen! Die Funktion neue-funktion() ist aber (zumindest für den der­zeitigen Stand von XPath) nicht verfügbar, der Test gibt also false zurück.

Beispiel 3 – Test einer Erweiterungsfunktion:

function-available('super:neue-funktion')

Ist für das Präfix super: ein Namensraum definiert, der beim Aufruf im Scope ist, so wird die angefragte Funktion super:neue-funktion() als Erweite­rungsfunktion betrachtet. Ist diese dem System bekannt, so wird der Wert true zurückgegeben, ansonsten false.

Beispiel 4 – Test einer Erweiterungsfunktion und deren Arity:

function-available('super:neue-funktion',3)

Gibt true zurück, wenn die Funktion mit dem geforderten Namen und der geforderten Zahl von Eingangsargumenten verfügbar ist, ansonsten false.

Prinzipiell erlaubt XSLT die gleichzeitige Existenz von zwei oder mehr gleich benannten Funktionen, die sich durch die Zahl ihrer Argumente unterschei­den. Mit dem Test aus Beispiel 3 kann jedoch nicht zwischen derartigen Namens­dubletten differenziert werden, sodass ein solcher Test nicht geeignet ist, einen nachfolgenen Funktionsaufruf mit der falschen Argumentzahl zu unterbinden.

Vorsicht – Prüfung des erwarteten Datentype nicht möglich!
Eine Prüfung des von der Funktion jeweils erwarteten Datentyps eines Eingangsarguments ist nicht möglich; ein Laufzeitfehler kann noch immer auftreten, wenn zwar Funktionsname und Zahl der Argumente stim­men, nicht aber die für die Argumente erwarteten Datentypen.

Beispiel 5 – Test einer Stylesheetfunktion (XSLT 2.0):

<!-- Deklaration: -->
<xsl:function name="meine:funktion">
  <!-- Anweisungsblock der Funktion -->
  ...
</xsl:function>
...
<xsl:if test="function-available('meine:funktion')">
  <!-- Instruktionen, die die Funktion verwenden -->
  ...
</xsl:if>
...

Eine mit xsl:function deklarierte Stylesheet-Funktion kann ebenfalls mit function-available() abgeprüft werden. Dies kann bei Verarbeitung durch einen XSLT 1.0-Prozessor nützlich sein, der ja die Funktionsdeklaration ignoriert und ihm die Funktion nicht zur Verfügung steht. (Die Übergabe eines arity-Arguments ist kontraproduktiv, weil für XSLT 1.0-Prozessoren fehlerträchtig!)

Beispiel 6 – XPath 2.0-Funktion vs. Erweiterungsfunktion

Wenn einem im vorwärtskompatiblen Modus arbeitenden XSLT 1.0-Prozessor eine Erweiterungsfunktion alternativ zu einer nativen XPath 2.0-Funktion angeboten werden soll, muss gegbenenfalls verhindert werden, dass ein XSLT 2.0-Prozessor, der diese Erweiterungsfunktion nicht kennt, beim Einlesen des Stylesheets einen statischen Fehler meldet:

<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:set="http://exslt.org/sets" extension-element-prefixes="set">
  <xsl:template name="infoliste">
    <xsl:param name="info" /> 
    <xsl:variable name="info_ohne_doubletten">
      <xsl:choose>
        <!-- ein XSLT 1.0 Prozessor überspringt dies: -->
        <xsl:when test="number(system-property('xsl:version')) &gt; 2.0">
          <xsl:sequence select="distinct-values($info)"/>
        </xsl:when>
        <!-- Erweiterungsfunktion aufrufen, wenn verfügbar: -->
        <!-- XSLT 2.0 Prozessor ignoriert Block andernfalls -->
        <xsl:when test="function-available('set:distinct')" use-when="function-available('set:distinct')">
          <xsl:value-of select="set:distinct($info)"/>
        </xsl:when>
        <xsl:otherwise>
          <!-- Alternativer Block -->
          ...
        </xsl:otherwise>
      </xsl:choose>
    </xsl:variable>
    <!-- weitere Instruktionen -->
    ...
  </xsl:template> 
</xsl:stylesheet>

Zur Lösung des genannten Problems wird im zweiten <xsl:when>-Element die Funktion function-available() eingesetzt. Ein XSLT 1.0-Prozessor ignoriert das use-when-Attribut (das er nicht kennt) und wertet nur das test-Attribut aus. Kennt er die Erweiterungsfunktion, so führt er sie aus (für den Fall, dass dies nicht der Fall ist, kann im <xsl:otherwise>-Block Abhilfe geschaffen werden, z.B. in Form des Aufrufs eines EXSLT-Erweiterungstemplates).

Ein XSLT 2.0-Prozessor wird bei der Verarbeitung bereits das erste <xsl:when>-Element ausführen. Ein Problem tritt jedoch beim Einlesen auf, sobald der Prozessor die geforderte Erweiterungsfunktion nicht kennt. An dieser Stelle wird möglicherweise ein statischer Fehler gemeldet. Mit Hilfe des use-when-Attributs, in dem die Verfügbarkeit ebenfalls geprüft wird, wird der Prozessor veranlasst den betreffenden <xsl:when>-Block zu ignorieren.

Funktionsdefinition:

XSLT 1.0:

function-available(string) => boolean

XSLT 2.0:

function-available($function-name as xs:string) as xs:boolean

function-available($function-name as xs:string,
                   $arity as xs:integer) as xs:boolean

   

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Galileo Press, Rheinwerkallee 4, 53227 Bonn