fn:uri-collection

fn:uri-collection() as xs:anyURI*

fn:uri-collection($arg as xs:string?) as xs:anyURI*

This function is deterministic, context-dependent, and focus-independent. It depends on available URI collections, and static base URI.

The zero-argument form of the function returns the URIs in the default URI collection described in Dynamic Context Components.

If the value of $arg is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $arg is the empty sequence, the function behaves as if it had been called without an argument. See above.

The single-argument form of the function returns the sequence of URIs corresponding to the supplied URI in the available URI collections described in Dynamic Context Components.

By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [ERRFODC0003].

There is no requirement that the URIs returned by this function should all be distinct, and no assumptions can be made about the order of URIs in the sequence, unless the implementation defines otherwise.

A dynamic error is raised [ERRFODC0002] if no URI is supplied (that is, if the function is called with no arguments, or with a single argument that evaluates to an empty sequence), and the value of the default resource collection is absent.

A dynamic error is raised [ERRFODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [ERRFODC0002] if available resource collections provides no mapping for the absolutized URI.

A dynamic error may be raised [ERRFODC0004] if $arg is not a valid xs:anyURI.

In some implementations, there might be a close relationship between collections (as retrieved by the fn:collection function), and URI collections (as retrieved by this function). For example, a collection might return XML documents, and the corresponding URI collection might return the URIs of those documents. However, this specification does not impose such a close relationship. For example, there may be collection URIs accepted by one of the two functions and not by the other; a collection might contain items that do not have any URI; or a URI collection might contain URIs that cannot be dereferenced to return any resource.

Thus, some implementations might ensure that calling fn:uri-collection and then applying fn:doc to each of the returned URIs delivers the same result as calling fn:collection with the same argument; however, this is not guaranteed.

In the case where fn:uri-collection returns the URIs of resources that could also be retrieved directly using fn:collection, there are several reasons why it might be appropriate to use this function in preference to the fn:collection function. For example:

• It allows different URIs for different kinds of resource to be dereferenced in different ways: for example, the returned URIs might be referenced using the fn:unparsed-text function rather than the fn:doc function.

• In XSLT 3.0 it allows the documents in a collection to be processed in streaming mode using the xsl:stream instruction.

• It allows recovery from failures to read, parse, or validate individual documents, by calling the fn:doc (or other dereferencing) function within the scope of try/catch.

• It allows selection of which documents to read based on their URI, for example they can be filtered to select those whose URIs end in .xml, or those that use the https scheme.

• An application might choose to limit the number of URIs processed in a single run, for example it might process only the first 50 URIs in the collection; or it might present the URIs to the user and allow the user to select which of them need to be further processed.

• It allows the URIs to be modified before they are dereferenced, for example by adding or removing query parameters, or by redirecting the request to a local cache or to a mirror site.

For some of these use cases, this assumes that the cost of calling fn:collection might be significant (for example, it might involving retrieving all the documents in the collection over the network and parsing them). This will not necessarily be true of all implementations.