Resolving URIs

Saxon adopts a uniform approach to resolving and dereferencing these URIs.

The general approach is as follows:

• The supplied URI reference is first made absolute by resolving against a suitable base URI.

  SaxonC provides a number of methods for setting the base URI: SaxonProcessor.setcwd(); Xslt30Processor.setcwd() or XsltExecutable.setBaseOutputURI() for XSLT; XQueryProcessor.setQueryBaseURI() for XQuery; or DocumentBuilder.setBaseUri() for building documents.

• The resulting absolute URI is dereferenced by a 3-step process:

  1. It is first passed to a local user-supplied ResourceResolver, registered at the level of a particular component such as the XsltCompiler, XsltTransformer, XQueryCompiler, or XQueryEvaluator. If no resolver has been supplied, this stage is skipped.

     Most of these components provide a method setResourceResolver() (in Java) or a settable property ResourceResolver (in C#) allowing the resolver to be supplied using a lambda expression. In some cases (for legacy reasons) there are also specialized methods for particular kinds of resources: for example setURIResolver(), setSchemaURIResolver(), setUnparsedTextResolver(), setModuleURIResolver().

     Note that for SaxonC there is no way to supply such a resolver.

  2. If the local resolver fails to resolve the URI, it is passed to a resolver registered centrally with the Saxon Configuration. The default resolver at this level is designed to invoke a third-party library called the catalog resolver, which looks up known URIs in an XML-based catalog. By default there is a single built-in catalog containing local copies of popular W3C-defined resources such as the DTDs for XHTML and SVG. Additional catalog files can be registered using an API (Processor.setCatalogFiles() in Java, Processor.SetCatalogFiles() in C#, SaxonProcessor.setCatalog() in C++ and PHP, PySaxonProcessor.set_catalog() in Python), or from the command line, or from the Saxon configuration file.

     The catalog resolver for SaxonJ and SaxonC also has built-in support for URIs using the classpath and data schemes.

     The catalog resolver for SaxonCS also has built-in support for URIs using the data scheme.

  3. If the URI has still not been resolved, it is then dereferenced using standard mechanisms provided by the platform: for example, http URIs are dereferenced using the Java or .NET HTTP library, and file URIs using the Java or .NET file I/O libraries.

  A user-written ResourceResolver for the first two steps is typically written as a function (lambda expression) that takes a ResourceRequest as input, and produces a Source (Java) or Resource (C#) as output.

URIs used within an XML document to refer to external entities (including the DTD) are a little different since they are generally handled by the XML parser, and not by Saxon itself. Nevertheless, Saxon attempts to offer an integrated approach. For more information on this, see Resolving entities.

URIs for result documents produced using the xsl:result-document instruction are handled using a ResultDocumentHandler registered with the XsltTransformer or Xslt30Transformer. For more information on how this works in both the Java s9api API and the Saxon.Api interface on .NET, see Secondary output.