fn:doc

(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: Assoziation und Auffindung von Nodes und Ressourcen

Herkunft: XPath 2.0

Rückgabewert: Der Document-Node eines externen Dokuments, wie es durch den übergebenen URI-String bestimmt wurde

Aufruf/Argumente:

fn:doc($document-uri?)

$document-uri:
Das einzige Argument der Funktion ist ein String vom Typ xs:string, der jedoch lexikalisch dem Typ xs:anyURI entsprechen muss. Han­delt es sich um einen relativen URI, so wird er gemäß dem Basis-URI des stati­schen Kontexts aufgelöst. Der übergebene URI-String darf ausdrücklich auch einen Fragment-Identifier enthalten. Wird als Argument der leere String übergeben, so gibt die Funktion den leeren String zurück.

Verwendungszweck:

Die Funktion gibt eine Sequenz zurück, bestehend aus einem Document-Node eines externen Dokuments, das in die Verarbei­tung eingebunden werden soll. Die Funktion existiert parallel zur komplexeren XSLT-Funktion document() und wurde in den XPath-Core übernommen, um diese Funktionalität ohne unnötigen Überbau auch außerhalb des XSLT-Kontex­tes zur Verfügung zu haben. Sie ist also eher für Anwendung in reinen XQuery-Situationen gedacht, ihrer Anwendung im XSLT-Kontext steht jedoch nichts im Wege.

Das einzige zu übergebende Funktionsargument dient der Auffindung der externen Ressource. Es handelt sich daher um einen String, der lexikalisch dem Typ xs:anyURI entsprechen soll:

fn:doc($document-URI)

Aufgelöst wird er hierbei gegenüber dem Basis-URI des statischen Kontexts, was folgendermaßen umschrieben werden könnte:

fn:doc(fn:resolve-uri($document-URI, $static-base-URI))

Der übergebene URI-String schließt auch die Möglichkeit des leeren Strings ein, wodurch die Funktion fn:doc() auf das Stylesheetdokument selbst zeigt:

fn:doc(fn:resolve-uri('', $static-base-URI))

Kann die so identifizierte Ressource nicht eingebunden werden, so wird eine Fehlermeldung ausgegeben (»Error retrieving resource«, err:FODC0002). Dies mag auch geschehen, falls das Laden einer externen Ressource eine Authentifizierung erfordern sollte – die Lösung, ob und auf welche Weise diese gegebenenfalls erfolgen kann, wird der Implementierung überlassen.

Die Unmöglichkeit, unmittelbar einen Basis-URI zu nennen, auf den der aus­zuwertende URI-String zu beziehen ist, hat Probleme zur Folge, wenn ein sich so ergebender relativer URI nicht gegenüber dem statischen Kontext (static con­text) des Aufrufes aufgelöst werden soll:

Stammt der übergebene URI-String nämlich – was in der Mehrzahl der Fälle so sein wird – aus einem verarbeiteten Quelldokument, so ist eher beabsichtigt, zur Auflösung den Basis-URI jenes Quellkontextes zu verwenden.

In diesem Fall muss, wie oben bei den verdeutlichenden Beispielen geschehen, die Funktion resolve-uri() zu Hilfe genommen und vor der Anwendung von fn:doc() auf den ihr übergebenen URI-String angewendet werden. Auf die­sem Umweg kann der Funktion fn:doc() der benötigte absolute URI-String zur Verfügung gestellt werden.

Fragment-Identifier, die auf eine Unterressource der angegebenen Hauptres­source zeigen, sind innerhalb des übergebenen URI-Strings gestattet. Dies ist analog zur Funktion document(), die sich jedoch nur im reinen XSLT-Kontext anwenden lässt. Ob und auf welche Weise ein solcher Fragment-Identifier beim Auflösen der URI-Information verwendet wird, ist abhängig von der Implementierung – die Spezifikation lässt dies offen. Alternativ kann man für den gleichen Effekt auf eine mittels fn:doc() eingebundene Ressource weitere XPath-Ausdrücke anwenden.

Die Funktion fn:doc() gilt im Sinne der XPath-Sprachregelung als stabil (stable), sodass ein Aufruf mit dem gleichen Argument während der Laufzeit einer Verarbeitung zuverlässig denselben Wert zurückgibt, also jeweils einen identischen Document-Node eines externen Dokuments. Es wird demzufolge ein relativer URI konstant zum gleichen absoluten URI aufgelöst.

Verhalten gegenüber dem Media-Type der Ressource
Ist die externe Res­source erfolgreich aufgefunden, so wird sie in Form einer Baumstruktur in die Verarbeitung eingebunden. Hierfür wird der Inhalt in Abhängigkeit vom Media-Type der Ressource geparst, sofern dieser an Hand des Toplevel-Elements zu ermit­teln ist. Ist der erkannte Media-Type »text«, so wird das Parsing gemäß des Ver­haltens für text/xml vorgenommen, andernfalls gemäß des Typs applica­tion/xml.

Ist das Parsing nicht möglich, wird ein entsprechender Fehler ausgegeben (»Error parsing contents of resource«, err:FODC0002).

Implementationsabhängige Aspekte der Funktion
Weitere Verarbeitungsas­pekte werden von vornherein der jeweiligen Implementierung der Funktion überlassen, können also von Anwendung zu Anwendung differieren. Dies bezieht sich auf:

• Syntax der unterstützten URI-Schemata. Es kann der Implementation erlaubt sein, es dem Nutzer zu überlassen, in welcher Form URIs mit Ressourcen verknüpft werden, z.B. in Form von Katalogen oder URI-Handlern.

• Das Verhalten gegenüber Nicht-XML-Ressourcen. Es kann durch die Imple­mentierung gestattet werden, für weitere Media-Typen außer den oben genannten, zur Einbindung Datenmodell-Instanzen zu erzeugen.

• Die Durchführung einer Validierung der eingebundenen Ressource gemäß einer DTD oder eines Schemas ist der Implementierung überlassen.

• Die Fehlerbehandlung bei Nichterreichbarkeit der Ressource oder Problemen bei deren Validierung oder Verarbeitung. In diesem Fall ist es der Imple­mentation überlassen, wie fortzufahren ist. Vorschläge bestehen in der Rück­gabe einer leeren Sequenz durch die Funktion oder dem Einbinden eines Fall­back-Dokuments durch den Error-Handler.

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:doc($uri as xs:string?) as document-node()?

   

<< zurück

vor >>