EXSLT - res:document

Implementer Page: res.document.html
Function Package: res.document.zip

Function Syntax

node-set res:document(object, node-set?, number?)

The res:document function has the same behavior as the document function with the following significant differences. Where the document function recursively calls itself, the res:document function follows the same pattern but calls itself, instead. For this description, the result namespace prefix maps to the http://exslt.org/resource/result URI.

Unlike the document function, the res:document function allows the user to specify an attempt index. The attempt index is the optional third argument to this function, and it defaults to 1. Two result documents returned by this function are treated as the same document if the documents that this function attempts to retrieve are identified by the same URI reference and are retrieved with the same attempt index. As a result, a processor can obtain new representations of a given URI for different values of the attempt index, but the following expressions will always be true:

generate-id(res:document("foo.xml"))=generate-id(res:document("foo.xml"))
generate-id(res:document("foo.xml", ., 1))=generate-id(res:document("foo.xml", ., 1))
generate-id(res:document("foo.xml"), ., 2)=generate-id(res:document("foo.xml", ., 2))

Although the following expression will not be true:

generate-id(res:document("foo.xml", ., 1))=generate-id(res:document("foo.xml", ., 2))

For any given value of the attempt index, this function behaves as follows.

When the first argument to the res:document function is not a node-set, this function performs the same processing as the document function, but instead of returning the constructed node-set, it returns a result node-set that is defined as follows. If the constructed node-set contains only a document node, then the encapsulated node-set is the set of all child nodes of this document node. Otherwise, the encapsulated node-set is the constructed node-set. The result node-set, which is returned from this function, consists of a result:success element with the encapsulated node-set as its children. This element MUST have an attempt attribute that contains the attempt index of this call and SHOULD also have a uri attribute that contains the absolute URI that this function retrieved. If there is an error processing the arguments or retriving the resource, then this function returns the node-set containing the root of a tree of the following form:

<result:error xmlns:result="http://exslt.org/resource/result"
              uri="http://www.example.org/"
              attempt="2">
  <result:failed>
    <result:category>protocol</result:category>
    <result:item>http</result:item>
  </result:failed>
  <result:code>404</result:code>
  <result:message>Not Found</result:message>
</result:error>

The elements contained in this error descriptor are mandatory unless stated otherwise. In such an error descriptor, the attempt attribute MUST contain the attempt index of this call and the uri attribute SHOULD contain the URI reference that triggered the error. The result:failed element MUST contain a result:category element and MAY contain a result:item element. The result:category element indicates the area of failure. Its value SHOULD be one of "relative-reference", "scheme", "connection", "protocol", "XML", or "fragment" to indicate an unresolvable relative URI reference, an unsupported scheme, problems in the network, problems with a particular document exchange protocol, problems in the resulting document, or problems processing the fragment identifier, respectively, or some other application-specific value to indicate a different type of problem. If the value of the result:category element is not "relative-reference", then the uri attribute of the result:error element MUST contain an absolute URI. If the value of the result:category element is "protocol", then the result:item element SHOULD contain the name of the protocol (as listed in the TCP and UDP Port Numbers list) that failed. The result:code element is optional, and SHOULD contain the error code corresponding to the error, if such a code exists. The result:message element is also optional, and contains any error message that was provided by the source of the error. Processors MAY add elements or attributes to the error descriptor with additional information, but these elements SHOULD be in a namespace other than http://exslt.org/resource/result.

Examples

Function

The following example shows how to use the res:document function:

Source

<doc>
   <result-from uri="http://www.example.org/" />
   <result-from uri="data.xml" />
   <p>Note that "data.xml" refers to this document.</p>
   <result-from uri="http://www.microsoft.com/license/GPL" />
</doc>

Stylesheet

<xsl:template match="/doc">
   <output>
      <xsl:copy-of select="res:document(result-from[1]/@uri)" />
      <xsl:copy-of select="res:document(result-from[2]/@uri)" />
      <xsl:copy-of select="res:document(result-from[3]/@uri)" />
   </output>
</xsl:template>

Result

<output xmlns:result="http://exslt.org/resource/result">
   <result:error uri="http://www.example.org/"
                 attempt="1">
      <result:uri>http://www.example.org/</result:uri>
      <result:failed>
         <result:category>connection</result:category>
      </result:failed>
      <result:message>Connection refused</result:message>
   </result:error>
   <result:success uri="file:///some/path/to/data.xml"
                   attempt="1">
      <doc>
         <result-from uri="http://www.example.org/" />
         <result-from uri="data.xml" />
         <p>Note that "data.xml" refers to this document.</p>
         <result-from uri="http://www.microsoft.com/license/GPL" />
      </doc>
   </result:success>
   <result:error uri="http://www.microsoft.com/license/GPL"
                 attempt="1">
      <result:failed>
         <result:category>protocol</result:category>
         <result:item>http</result:item>
      </result:failed>
      <result:code>404</result:code>
      <result:message>Not Found</result:message>
   </result:error>
</output>