XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

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

fn:doc

Category:

Association and localisation of nodes and resources at runtime

Origin:

XPath 2.0

Return value:

The document node of an external document as determined by the URI string passed on.

Call/Arguments:

fn:doc($document-uri?)

$document-uri:

The only argument of the function is a string of xs:string type which, however, has to lexically correspond to the xs:anyURI type. If the URI is a relative URI, it is resolved according to the base URI of the static context. The URI string passed on is expressively allowed to also contain a fragment identifier. If the empty string is passed on as argument, the funtion returns the empty string.

Purpose of use:

The funtion returns a sequence consisting of a document node of an external document which shall be included in the processing. The function exists in parallel to the more complex XSLT function document() and was introduced within the scope of the XPath Core in order to have this functionality also available outside the XSLT context without unnecessary superstructure. Therefore, the function is rather intended for applications in mere XQuery situations, but there is no reason why you should not use it in the XSLT context.

The only function argument to be passed on is used for the addressing of the external resource. Therefore, it is a string which shall lexically correspond to the xs:anyURI type:

fn:doc($document-URI)

the URI string is resolved based on the base URI of the static context which may be rewritten in the following way:

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

The URI string to be passed on also includes the possibility of the empty string, whereby the fn:doc() function itself points at the stylesheet document:

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

If the resource identified in this way cannot be embedded, an error message is outputted (»Error retrieving resource«, err:FODC0002). This may also occur if the loading of the external resource requires an authentication. The solution and whether and how it may be realised, is left to the implementation.

The impossibility to directly name a base URI on which the URI string to be evaluated shall be referred may cause problems in case a relative URI resulting from this cannot be resolved on the basis of the static context of the call:

If the URI string passed on comes – which will be mostly the case – from a processed source document, it is rather intended to use the base URI for the resolution.

In this case, as happened above for the examples, the fn:resolve-uri() function must be used as a help and applied on the URI string passed on to it before the application of fn:doc(). Via this detour, the fn:doc() function can be provided with the required absolute URI string.

Fragment identifiers which point at a subresource of the indicated main resource are permitted within the URI string passed on. This is analogous to the document() function which, however, can only be used in the mere XSLT context. Whether and how such a fragment identifier is used when resolving the URI information depends on the implementation – the specification leaves this open. Alternatively, for having the same effect, further XPath expressions can be applied to a resource embedded by means of fn:doc().

The fn:doc() function is regarded as stable in the sense of the XPath language regulation, so that a call with the same argument returns reliably the same value during the runtime of a processing which means an identical document node of an external document. Thus, a relative URI is constantly resolved to the same absolute URI.

Behaviour towards the media type of the resource:

If the external resource is successfully addressable, it will be embedded in the processing in the form of a tree structure. This is realised depending on the media type of the resource provided that it can be determined by means of the top-level element. If the recognised type is »text«, the resource is parsed according to the behaviour for text/xml, otherwise according to the application/xml type.

In case the parsing is impossible, an appropriate error is outputted (»Error parsing contents of resource«, err:FODC0002).

Implementation-depending aspects of the function:

Further processing aspects are left, from the outset, to the respective implementation of the function. So they can differ from application to application. This refers to:

  • The syntax of the supported URI schemata. The implementation may leave it to the user in which form URIs shall be connected with resources, for example in the form of catalogues or URI handlers.
  • The behaviour towards non-XML resources. The implementation may allow to generate for further media types, except for the ones mentioned above, data model instances for the embedding.
  • The validation of the embedded resource according to a DTD or a schema is left to the implementation.
  • The error handling in the event of non-accessibility of the resource or problems during its validation or processing. In this case, it is left to the implementation how to continue. Proposals are the return of an empty sequence by the function or the embedding of a fallback document by the error handler.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

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

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany